Kube-secret-syncer
Kube-secret-syncer is a Kubernetes operator developed using the Kubebuilder framework that keeps the values of Kubernetes Secrets synchronised to secrets in AWS Secrets Manager.
This mapping is described in a Kubernetes custom resource called SyncedSecret. The operator polls AWS for changes in secret values at regular intervals, and upon detecting changes, updates the Kubernetes Secrets.
WARNING: updating the value of a secret in AWS SecretsManager will override secrets in Kubernetes, therefore can be a destructive action.
Comparison to existing projects
Kube-secret-syncer is similar to other projects such as:
Kube-secret-syncer improves on this approach:
- uses caching to only retrieve the value of secrets when they have changed, substantially reducing costs when syncing a large number of secrets.
- enables sophisticated access control to secrets in AWS SecretsManager using IAM roles - see our security model
- supports templated fields for Kubernetes secrets - enabling the use of values from multiple AWS SecretsManager secrets in one Kubernetes Secret
Defining mapping between an AWS SecretsManager secret and a Kubernetes Secret
The following resource will map the AWS Secret secretsyncer/secret/sample
to the Kubernetes Secret
demo-service-secret
, and copy all key-value pairs from the AWS SecretsManager secret to the Kubernetes secret For
this example, the AWS SecretsManager secret needs to be a valid JSON consisting only of key-value pairs.
To access the secrets, kube-secret-syncer will assume the role iam_role
to poll the secret. Note: that role must be
assumed by the Kubernetes cluster/node where the operator runs, eg part of the kube2iam annotation on the namespace.
apiVersion: secrets.contentful.com/v1
kind: SyncedSecret
metadata:
name: demo-service-secret
namespace: kube-secret-syncer
spec:
IAMRole: iam_role
dataFrom:
secretRef:
name: secretsyncer/secret/sample
If you only need to retrieve select keys in a single AWS secret, or multiple keys from different AWS secrets, you can use the following syntax:
apiVersion: secrets.contentful.com/v1
kind: SyncedSecret
metadata:
name: demo-service-secret
namespace: kube-secret-syncer
spec:
IAMRole: iam_role
data:
# Sets the key mysql_user for the Kubernetes Secret "demo-service-secret" to "contentful"
- name: mysql_user
value: "contentful"
# Takes the value for key "password" from the Secrets Manager secret "mysql", assign to the
# key "mysql_pw" of the Kubernetes secret "demo-service-secret"
- name: mysql_pw
valueFrom:
secretKeyRef:
name: mysql
key: password
- name: datadog_access_key
valueFrom:
secretKeyRef:
name: datadog
key: access_key
You can also chose to store non-JSON values in AWS Secret Manager, which might be more convenient for data such as certificates.
apiVersion: secrets.contentful.com/v1
kind: SyncedSecret
metadata:
name: demo-service-secret
namespace: kube-secret-syncer
spec:
IAMRole: iam_role
data:
# Sets the key ssl-certificate for the Kubernetes Secret "demo-service-secret"
# to the value of the secret "apache/ssl-cert"
- name: ssl-certificate
valueFrom:
secretRef:
name: apache/ssl-cert
Templated fields
Kube-secret-syncer supports templated fields. This allows, for example, to iterate over a list of secrets that share the same tag, to output a configuration file, such as in the following example:
apiVersion: secrets.contentful.com/v1
kind: SyncedSecret
metadata:
name: pgbouncer.txt
namespace: kube-secret-syncer
spec:
IAMRole: iam_role
data:
- name: pgbouncer-hosts
valueFrom:
template: |
{{- $cfg := "" -}}
{{- range $secretID, $_ := filterByTagKey .Secrets "tag1" -}}
{{- $secretValue := getSecretValueMap $secretID -}}
{{- $cfg = printf "%shost=%s user=%s password=%s\n" $cfg $secretValue.host $secretValue.user $secretValue.password -}}
{{- end -}}
{{- $cfg -}}
This iterates over all secrets kube-secret-syncer has access to, select those that have the tag "tag1" set, and for each of these, add a configuration line to $cfg. $cfg is then assigned to the key "pgbouncer-hosts" of the Kubernetes secret pgbouncer.txt.
The template is a Go template with the following elements defined:
.Secrets
- a map containing all listed secrets (without their value)filterByTagKey
- a helper function to filter the secrets by taggetSecretValue
- will retrieve the raw value of a Secret in SecretsManager, given its secret IDgetSecretValueMap
- will retrieve the value of a Secret in SecretsManager that contains a JSON, given its secret ID - as a map
Caching
Kube-secret-syncer maintains both the list of AWS Secrets as well as their values in cache. The list is updated every
POLL_INTERVAL_SEC
, and values are retrieved whenever their VersionID changed.
Security model
By default, kube-secret-syncer will use the Kubernetes node's IAM role to list and retrieve the secrets. However, when synced secrets have an IAMRole field defined, kube-secret-syncer will assume that role before retrieving the secret. This implies that the role specified by IAMRole can be assumed by the role of the Kubernetes node kube-secret-syncer runs on.
To ensure a specific namespace only has access to the secrets it needs to, kube-secret-syncer will use the "iam.amazonaws.com/allowed-roles" annotation on the namespace (originally used by kube2iam) to validate that this role can be assumed for that namespace.
The secret synchronisation will be allowed if:
- the annotation is set on the namespace and contains the secrets IAMRole
- no annotation is set on the namespace and the secret has a IAMRole set
- no annotation is set on the namespace and the secret has no IAMRole set
The secret sync will be denied if:
- the annotation is set on the namespace and does not contains the secrets IAMRole
- the annotation is set on the namespace and the secret has no IAMRole set
Configuration
Kube-secret-syncer supports the following environment variables:
POLL_INTERVAL_SEC
: how often the list of secrets in cache is refreshed (default:300
)SYNC_INTERVAL_SEC
: how often we will write to a Kubernetes secret (default:120
)NS_ANNOTATION
: the annotation on the namespace that contains a list of IAM roles kube-secret-syncer is allowed to assume (default:iam.amazonaws.com/allowed-roles
)METRICS_LISTEN
: what interface/port the metrics server shoult listen on (default::8080
)
Note - when a secret in Secrets Manager is updated, the secret in Kubernetes will not be updated until both the list of secrets is refreshed AND the sync_interval expires - therefore it might take up to POLL_INTERVAL_SEC + SYNC_INTERVAL_SEC.
Local development
Please refer to the local development documentation.
Examples
See sample configurations and deployment example.