Skip to content

Ansible Role linuxfabrik.lfops.elastic_agent_fleet_server

This role installs and configures Elastic Agent as a Fleet Server. The Fleet Server acts as the control plane for managing Elastic Agents and connecting them to Elasticsearch and Kibana.

Available since LFOps 6.0.0.

Dependent Roles

Any LFOps playbook that installs this role runs these for you. Optional ones can be disabled via the playbook's skip variables.

Requirements

  • A running Elasticsearch cluster must be reachable.

Manual steps:

  • Deploy Elasticsearch by running the elasticsearch playbook (role: linuxfabrik.lfops.elasticsearch).
  • Generate a Fleet Server service token using the Elasticsearch API or Kibana (Fleet -> Add Fleet Server). See below.
  • Optionally, generate TLS certificates for the Fleet Server using the Elasticsearch certutil tool. See below.

Generate Service Token

Generate a service token for the Fleet Server using the Elasticsearch API:

elastic_host='localhost'
elastic_cacert='/etc/elasticsearch/certs/http_ca.crt'
fleet_server_name="$(hostname --fqdn)"

curl --cacert "$elastic_cacert" \
    --user "elastic:${ELASTIC_PASSWORD}" \
    --request POST "https://$elastic_host:9200/_security/service/elastic/fleet-server/credential/token/$fleet_server_name?pretty=true" \
    --header "Content-Type: application/json"

Store the value field from the response as elastic_agent_fleet_server__service_token.

Alternatively, the token can be taken from Kibana (Fleet -> Add Fleet Server).

Generate TLS Certificates (Optional)

If you want TLS for the Fleet Server, generate certificates using the Elasticsearch certutil tool. On the node where Elasticsearch CA lives:

cat > /tmp/fleet-server-cert.yml <<EOF
instances:
  - name: 'fleet-server.example.com'
    ip:
      - '127.0.0.1'
      - '192.0.2.10'
    dns:
      - 'localhost'
      - 'fleet-server.example.com'
      - 'fleet-server'
EOF

/usr/share/elasticsearch/bin/elasticsearch-certutil cert \
  --ca-cert /etc/elasticsearch/ca/ca.crt \
  --ca-key /etc/elasticsearch/ca/ca.key \
  --in /tmp/fleet-server-cert.yml \
  --pem \
  --out /tmp/fleet-server-certs.zip

Copy the generated certificates to the Ansible inventory. The certificates are used for:

  • elastic_agent_fleet_server__elasticsearch_ca - The CA certificate (same as Elasticsearch CA)
  • elastic_agent_fleet_server__ssl_cert - The Fleet Server certificate
  • elastic_agent_fleet_server__ssl_key - The Fleet Server private key

Tags

elastic_agent_fleet_server

  • Installs and configures elastic-agent as Fleet Server.
  • Triggers: none.

elastic_agent_fleet_server:certs

  • Deploys TLS certificates.
  • Triggers: none.

elastic_agent_fleet_server:enroll

  • Enrolls the agent as Fleet Server.
  • Triggers: none.

elastic_agent_fleet_server:state

  • Manages the state of the elastic-agent service.
  • Triggers: none.

Mandatory Role Variables

elastic_agent_fleet_server__elasticsearch_host

  • Elasticsearch URL. Will only be used for the initial connection, so the node's role is irrelevant. Afterwards, the output defined in the policy will be used.
  • Type: String.
  • Default: none

elastic_agent_fleet_server__service_token

  • The service token for authenticating the Fleet Server to Elasticsearch. Generate using the Elasticsearch API.
  • Type: String.
  • Default: none

Example:

# mandatory
elastic_agent_fleet_server__elasticsearch_host: 'https://ingest1.example.com:9200'
elastic_agent_fleet_server__service_token: 'AAEAAWVsYXN0aWMvZmxlZXQtc2VydmVyL3Rva2VuMTpTTHVuZERNWlJJR...'

Optional Role Variables

elastic_agent_fleet_server__elasticsearch_ca

  • ASCII-armored PEM CA certificate for verifying Elasticsearch TLS (Fleet Server -> Elasticsearch).
  • Type: String.
  • Default: unset

elastic_agent_fleet_server__insecure

  • Skip TLS verification. Only use for testing with self-signed certificates.
  • Type: Bool.
  • Default: false

elastic_agent_fleet_server__policy_id

  • The Fleet Server policy ID. Must exist in Kibana Fleet.
  • Type: String.
  • Default: 'fleet-server-policy'

elastic_agent_fleet_server__service_enabled

  • Enables or disables the elastic-agent service, analogous to systemctl enable/disable.
  • Type: Bool.
  • Default: true

elastic_agent_fleet_server__service_state

  • The state of the elastic-agent service. Possible options: started, stopped, restarted.
  • Type: String.
  • Default: 'started'

elastic_agent_fleet_server__ssl_cert

  • ASCII-armored PEM TLS certificate for the Fleet Server (Fleet Agent -> Fleet Server).
  • Type: String.
  • Default: unset

elastic_agent_fleet_server__ssl_key

  • ASCII-armored PEM TLS private key for the Fleet Server (Fleet Agent -> Fleet Server).
  • Type: String.
  • Default: unset

elastic_agent_fleet_server__url

  • The URL of the Fleet Server. Used by agents to connect.
  • Type: String.
  • Default: 'https://{{ ansible_facts["nodename"] }}:8220'

Example:

# optional
elastic_agent_fleet_server__elasticsearch_ca: '{{ lookup("ansible.builtin.file", inventory_dir ~ "/group_files/elasticsearch/ca.crt") }}'
elastic_agent_fleet_server__insecure: false
elastic_agent_fleet_server__policy_id: 'fleet-server-policy'
elastic_agent_fleet_server__service_enabled: true
elastic_agent_fleet_server__service_state: 'started'
elastic_agent_fleet_server__ssl_cert: '{{ lookup("ansible.builtin.file", inventory_dir ~ "/host_files/" ~ inventory_hostname ~ "/fleet-server.crt") }}'
elastic_agent_fleet_server__ssl_key: '{{ lookup("ansible.builtin.file", inventory_dir ~ "/host_files/" ~ inventory_hostname ~ "/fleet-server.key") }}'
elastic_agent_fleet_server__url: 'https://fleet.example.com:8220'

License

The Unlicense

Author Information

Linuxfabrik GmbH, Zurich