# README
Vault Integration
This repository provides the elements for the integration of edgefarm with Hashicorp Vault.
Component certretrieval
This component implements automatic login to Vault and retrieval of X.509 certificates. The component requires an initial vault token that allows authenticating against vault. The token must be associated with a suitable role that allows creating certificates for a configured common name. The token can be deployed using a flat file or the app may use a k8s service account to retrieve it itself.
The process retrieves the new certificate from Vault and stores it into local files. Existing files are overwritten, however this is done atomically by renaming a temporary file. This assures that no partial certificates are visible to using processes.
Configuration via commandline
The process may be configured using command line parameters, text file (for use with k8s config maps) and environment variables. Commandline parameters take precedence over environment variabels.
| Commandline Arg | Environment Variable | Description |
|---|---|---|
| tokenfile | VAULT_TOKEN_FILE | The Vault token that authenticates the request to Vault. Is used as bearer token. |
| vault | VAULT_ADDR | The URL of the Vault server. |
| serverca | VAULT_CACERT | A ca certificate for validating the Vault server certificate, if self-signed certificates are used. |
| role | ROLE | The Vault role name for generating a new certificate. The rolename will be passed to Vault and defines the parameters for the new certificate. The role must already be configured within Vault. |
| authrole | AUTH_ROLE | Only when using the kubernetes authentication to retrieve the Vault token. Defines the role to be used when authenticating. The role must already have been defined in Vault. |
| name | COMMON_NAME | The common name to be used for the new certificate. |
| ca | CA_FILE | Target filename for the issuing CA certificate, stored in PEM format. |
| cert | CERT_FILE | Target filename for the new certificate, stored in PEM format. |
| key | KEY_FILE | Target filename for the private key associated with the new certificate, stored in PEM format. |
| checktolerance | n/a | If defined, the validity of the current certificate is checked. If the certificate is not stale, the retrieval of a new certificate is skipped. The tolerance defines how close to the end of the validity period the certificate has to be: e.g. 80 means that the certificate is considered stale, if only 20% of the validity period remain. |
| ttl | TTL | The time to live of the newly created certificate. The server may impose a shorter limit. |
| config | n/a | A text file containing the configuration (see below). |
| loopdelay | n/a | If defined, the process will not terminate after retrieval, but sleep for the given delay before the next retrieval in a endless loop. Note that the configfile is not re-read between loops |
Configuration via configfile
To facilitate the usage within kubernetes, the component may also read a config file containing key=value pairs.
Example:
authrole=cloudcore
force=false
name=cloudcore.edgefarm.io
ca=/etc/kubeedge/certs/rootCA.crt
cert=/etc/kubeedge/certs/edge.crt
key=/etc/kubeedge/certs/edge.key
role=server
serverca=/opt/certretrieval/cert/ca.crt
ttl=24h
vault=https://vault.edgefarm.io
The file is passed using -config parameter and is intended for usage within kubernetes, where configuration may be passed as configmap.
Technical documentation
More in-depth documentation for concepts, setup and configuration is found here