227bf82 Dec 12, 2018
2 contributors

Users who have contributed to this file

@pingles @mikesplain
58 lines (40 sloc) 2.09 KB


This guide will generate certificates with a short expiry. It will help you get something running but when deploying to production please ensure you automate certificates using a tool like Vault, cert-manager etc.

Kiam is split into two processes:

  • Agent. Responsible for receiving HTTP connections that Pods initiate to the metadata API ( Credential requests are processed and anything else is forwarded to the AWS API. Communicates with the server via gRPC.
  • Server. Runs the gRPC server that Agent uses to determine Pod roles and retrieve credentials.

To ensure that only agents and servers can communicate with each other they use mutual TLS authentication. These are not automatically generated so you'll need to create the certificates and store in secrets that only Server and Agent processes can access.

Breaking Change in v3.0

In 3.0 a fix was made to the TLS ServerName configuration. This changed the validation to only check the host (rather than the address). The configuration for the server certificate has been updated.

If you generated your own certificates you will need to additively update them to include only the host to avoid breaking server/agent communication.

Install the helper tool

go get -u

Generate certs

Sample cert json data provided in the docs directory.

  1. Create the Certificate Authority Cert and Key
cfssl gencert -initca ca.json | cfssljson -bare ca
  1. Create Server pair
cfssl gencert -ca=ca.pem -ca-key=ca-key.pem server.json | cfssljson -bare server
  1. Create Agent pair
cfssl gencert -ca=ca.pem -ca-key=ca-key.pem agent.json | cfssljson -bare agent

Store in Kubernetes

kubectl create secret generic kiam-server-tls -n kube-system \
  --from-file=ca.pem \
  --from-file=server.pem \
kubectl create secret generic kiam-agent-tls -n kube-system \
  --from-file=ca.pem \
  --from-file=agent.pem \