Secret files guide
editSecret files guide
editThis 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.
Secrets on filesystem
editSecret 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
editFile 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 # set the user:group to root sudo chmod 0600 mySecret # 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 # Create the file mySecret with the contents SECRET icacls .\mySecret /inheritance:d # Remove inherited permissions from file icacls .\mySecret /remove:g BUILTIN\Administrators # Remove Administrators group permissions icacls .\mySecret /remove:g $env:UserName # Remove current user's permissions
Temporary filesystem
editYou 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.
Example
editHere 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
The -n
flag is used with echo
to prevent a newline character from being appended at the end of the secret. Be sure that the secret file does not contain the trailing newline character.
Secrets in containers
editWhen 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/beats/elastic-agent
Secrets in Kubernetes
editKubernetes 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/beats/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
Elastic Agent Kubernetes secrets provider
editWhen 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. Note that due to how Fleet Server is bootstrapped only the APM secrets (API key or secret token) can be specified with this provider.