autocert

Mutual TLS (mTLS) is a variant of the TLS protocol where both the client and the server authenticate to one another by presenting certificates. This differs from standard server-auth TLS (used by web browsers), where only the server is authenticated.

Key Benefits

• Authenticated Encryption: Provides both an identity dialtone and end-to-end encryption.
• Identity-Aware Workloads: Makes workloads identity-aware, improving observability and enabling granular access control.
• Secure Public Exposure: Services can be safely exposed to the public internet because only clients possessing a certificate issued by your internal Certificate Authority (CA) will be allowed to connect.

Requirements for mTLS

• Root Knowledge: Both client and server must have prior knowledge of the root certificate(s) used to sign the peer's certificate.
• Correct Configuration: Both parties must be configured with the correct certificate and private key (the certificate must be issued by a CA with a trusted root certificate).
• Private Key Security: Private keys must never be shared; they are used to prove identity through digital signatures without exposing the key itself.

Autocert is designed for managing private CA certificates for mTLS service-to-service communication in Kubernetes.

Key Security Concepts

• Key Generation: Private keys are generated locally within the workload via an initContainer and managed via volume mounts. This follows PKI best practices by ensuring private keys are never transmitted over the network or stored in plaintext in etcd (unlike Kubernetes Secrets).
• Bootstrap Tokens: The autocert admission webhook uses Kubernetes Secrets to securely transmit one-time bootstrap tokens to containers. This allows the autocert-bootstrapper to exchange the token for a certificate.
• RBAC Requirements: autocert requires cluster-wide permissions to create and delete secrets to manage these one-time tokens.
• Certificate Defaults: By default, it issues ECDSA certificates using the P256 curve with ECDSA-SHA256 signatures.

Comparison with cert-manager

While cert-manager is optimized for Web PKI (e.g., Let's Encrypt) for ingress TLS, autocert is purpose-built for private CA mTLS within a cluster.

To completely uninstall autocert, you must delete the mutating webhook configuration, the step namespace, and the associated RBAC artifacts.

Afterward, you should remove labels from all namespaces and clean up any remaining one-time token secrets. Sidecar containers will be removed once you remove the relevant annotations from your workloads and redeploy them.

# 1. Delete webhook, namespace, and RBAC
kubectl delete mutatingwebhookconfiguration autocert-webhook-config
kubectl delete namespace step
kubectl delete clusterrolebinding autocert-controller
kubectl delete clusterrole autocert-controller

# 2. Clean up namespace labels and stray secrets
for ns in $(kubectl get namespace --selector autocert.step.sm=enabled -o jsonpath='{$.items[*].metadata.name}'); do
  kubectl label namespace "$ns" autocert.step.sm-
  kubectl -n "$ns" delete secrets --selector="autocert.step.sm/token=true"
done

The hello-mtls examples provide dockerized mTLS (Mutual TLS) clients and servers in various languages. These examples demonstrate best practices such as using internal CA root certificates, implementing client authentication, and supporting short-lived certificate rotation.

To build the examples, use the multi-stage Docker builds provided in the repository. You will need docker installed locally. Replace <lang> with the specific language implementation you wish to build (e.g., go, node, curl).

Once built, you can deploy the client and server components to a Kubernetes cluster using the provided YAML manifests.

# Build the server
docker build -f Dockerfile.server -t hello-mtls-server-<lang> .

# Build the client
docker build -f Dockerfile.client -t hello-mtls-client-<lang> .

# Deploy to Kubernetes
kubectl apply -f hello-mtls.server.yaml
kubectl apply -f hello-mtls.client.yaml

If you cannot use the quickstart method, follow these steps to manually set up the CA and the autocert controller.

1. Prerequisites

• Install step CLI version 0.18.2 or later.
• Ensure you have cluster-admin permissions (on GKE, you may need to explicitly bind the cluster-admin role to your user).

2. Create a CA

First, set a temporary STEPPATH to stage CA artifacts:

export STEPPATH=$(mktemp -d /tmp/step.XXX)

Initialize the CA using step ca init. You will be prompted for a password to encrypt key material:

step ca init \
    --name Autocert \
    --dns "ca.step.svc.cluster.local,127.0.0.1" \
    --address ":4443" \
    --provisioner admin \
    --with-ca-url "ca.step.svc.cluster.local"

Add the autocert provisioner to the CA:

step ca provisioner add autocert --create

3. Install the CA in Kubernetes

Create the step namespace and upload the CA configuration, certificates, and secrets as ConfigMaps. You must also create Kubernetes secrets for the passwords used during CA initialization and provisioner creation.

Note: Use the exact passwords you entered during the step ca init and step ca provisioner add steps.

4. Install the autocert controller

Apply the controller manifest and the RBAC configuration to allow autocert to manage bootstrap token secrets.

5. Register the mutation webhook

Finally, register the autocert mutation webhook with Kubernetes to enable automatic certificate injection.

# 1. Quickstart (Alternative to manual)
kubectl run autocert-init -it --rm --image smallstep/autocert-init --restart Never

# 2. Manual: Create CA
export STEPPATH=$(mktemp -d /tmp/step.XXX)
step ca init \
    --name Autocert \
    --dns "ca.step.svc.cluster.local,127.0.0.1" \
    --address ":4443" \
    --provisioner admin \
    --with-ca-url "ca.step.svc.cluster.local"
step ca provisioner add autocert --create

# 3. Manual: Kubernetes Setup (Namespace and ConfigMaps)
kubectl create namespace step
kubectl -n step create configmap config --from-file $(step path)/config
kubectl -n step create configmap certs --from-file $(step path)/certs
kubectl -n step create configmap secrets --from-file $(step path)/secrets
kubectl -n step create secret generic ca-password --from-literal password=<ca-password>
kubectl -n step create secret generic autocert-password --from-literal password=<autocert-password>

# 4. Manual: Apply manifests
kubectl apply -f https://raw.githubusercontent.com/smallstep/autocert/master/install/01-step-ca.yaml
kubectl apply -f https://raw.githubusercontent.com/smallstep/autocert/master/install/02-autocert.yaml
kubectl apply -f https://raw.githubusercontent.com/smallstep/autocert/master/install/03-rbac.yaml