Secret files guide

This guide provides step-by-step examples with best practices on how to deploy secret files directly on a host or through the Kubernetes secrets engine.

Secret files can be provisioned as plain text files directly on filesystems and referenced or passed through Elastic Agent.

We recommend these steps to improve security.

File permissions should not allow for global read permissions.

On MacOS and Linux, you can set file ownership and file permissions with the chown and chmod commands, respectively. Fleet Server runs as the root user on MacOS and Linux, so given a file named mySecret, you can alter it with:

sudo chown root:root mySecret
sudo chmod 0600 mySecret

1. set the user:group to root
2. set only the read/write permission flags for the user, clear group and global permissions.

On Windows, you can use icacls to alter the ACL list associated with the file:

Write-Output -NoNewline SECRET > mySecret
icacls .\mySecret /inheritance:d
icacls .\mySecret /remove:g BUILTIN\Administrators
icacls .\mySecret /remove:g $env:UserName

1. Create the file mySecret with the contents SECRET
2. Remove inherited permissions from file
3. Remove Administrators group permissions
4. Remove current user's permissions

You can use a temporary filesystem (in RAM) to hold secret files in order to improve security. These types of filesystems are normally not included in backups and are cleared if the host is reset. If used, the filesystem and secret files need to be reprovisioned with every reset.

On Linux you can use mount with the tmpfs filesystem to create a temporary filesystem in RAM:

mount -o size=1G -t tmpfs none /mnt/fleet-server-secrets

On MacOS you can use a combination of diskutil and hdiutil to create a RAM disk:

diskutil erasevolume HFS+ 'RAM Disk' `hdiutil attach -nobrowse -nomount ram://2097152`

Windows systems do not offer built-in options to create a RAM disk, but several third party programs are available.

Here is a step by step guide for provisioning a service token on a Linux system:

sudo mkdir -p /mnt/fleet-server-secrets
sudo mount -o size=1G -t tmpfs none /mnt/fleet-server-secrets
echo -n MY-SERVICE-TOKEN > /mnt/fleet-server-secrets/service-token
sudo chown root:root /mnt/fleet-server-secrets/service-token
sudo chmod 0600 /mnt/fleet-server-secrets/service-token

When you are using secret files directly in containers without using Kubernetes or another secrets management solution, you can pass the files into containers by mounting the file or directory. Provision the file in the same manner as it is in Secrets on filesystem and mount it in read-only mode. For example, when using Docker.

If you are using Elastic Agent image:

docker run \
	-v /path/to/creds:/creds:ro \
        -e FLEET_SERVER_CERT_KEY_PASSPHRASE=/creds/passphrase \
        -e FLEET_SERVER_SERVICE_TOKEN_PATH=/creds/service-token \
        --rm docker.elastic.co/elastic-agent/elastic-agent

Kubernetes has a secrets management engine that can be used to provision secret files to pods.

For example, you can create the passphrase secret with:

kubectl create secret generic fleet-server-key-passphrase \
  --from-literal=value=PASSPHRASE

And create the service token secret with:

kubectl create secret generic fleet-server-service-token \
  --from-literal=value=SERVICE-TOKEN

Then include it in the pod specification, for example, when you are running Fleet Server under Elastic Agent:

spec:
  volumes:
  - name: key-passphrase
    secret:
      secretName: fleet-server-key-passphrase
  - name: service-token
    secret:
      secretName: fleet-server-service-token
  containers:
  - name: fleet-server
    image: docker.elastic.co/elastic-agent/elastic-agent
    volumeMounts:
    - name: key-passphrase
      mountPath: /var/secrets/passphrase
    - name: service-token
      mountPath: /var/secrets/service-token
    env:
    - name: FLEET_SERVER_CERT_KEY_PASSPHRASE
      value: /var/secrets/passphrase/value
    - name: FLEET_SERVER_SERVICE_TOKEN_PATH
      value: /var/secrets/service-token/value

When you are running Fleet Server under Elastic Agent in Kubernetes, you can use Elastic Agent's Kubernetes Secrets Provider to insert a Kubernetes secret directly into Fleet Server's configuration. Due to how Fleet Server is bootstrapped only the APM secrets (API key or secret token) can be specified with this provider.