certificates/autocert/RUNBOOK.md

# Runbook

## Common admin tasks

#### Recover `admin` and CA password

```
kubectl -n step get secret ca-password -o jsonpath='{$.data.password}' | base64 -D
```

#### Recover `autocert` password

```
kubectl -n step get secret autocert-password -o jsonpath='{$.data.password}' | base64 -D
```

#### Recompute root certificate fingerprint

```
export CA_POD=$(kubectl -n step get pods -l app=ca -o jsonpath={$.items[0].metadata.name})
kubectl -n step exec -it $CA_POD step certificate fingerprint /home/step/.step/certs/root_ca.crt
```

> Tip: Some slight fanciness is necessary to trim this string if you want to put it into an environment variable:
>
> ```
> export FINGERPRINT="$(kubectl -n step exec -it $CA_POD step certificate fingerprint /home/step/.step/certs/root_ca.crt | tr -d '[:space:]')"
> ```

#### Inspect a certificate

```
kubectl exec -it <pod> -c autocert-renewer -- step certificate inspect /var/run/autocert.step.sm/site.crt
```

#### Labelling a namespace (enabling `autocert` for a namespace)

To enable `autocert` for a namespace it must be labelled. To label an existing namespace run:

```
kubectl label namespace <namespace> autocert.step.sm=enabled
```

#### Checking which namespaces are labelled

```
kubectl get namespace -L autocert.step.sm
```

#### Removing a label from a namespace (disabling `autocert` for a namespace)

```
kubectl label namespace <namespace> autocert.step.sm-
```

#### Naming considerations

Use hostnames. Must be global. Everyone who connects to the service using mTLS must use the same hostname. For internal communication it's easy enough to use the FQDN of a service. For stuff you expose publicly you'll need to manage DNS yourself...

In any case, the critical invariant is: ...

Diagram here?

#### Cleaning up one-time token secrets

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

### TODO:
* Change admin password
* Change autocert password
* Federating with another CA
* DNS tips and tricks
* Multiple SANs
* Getting rid of the sidecar
* Getting logs from the CA (certificates weren't issued)
* Getting logs from the init container / renewer (didn't start properly)
* Adjusting certificate expiration (default 24h)
* Remove label
* Clean up secrets
* Naming considerations (maybe this should be in hello-mtls)

## Federation

TODO: Example of federating a CA running in kubernetes with another CA.

For now, see https://smallstep.com/blog/step-v0.8.3-federation-root-rotation.html

## Multiple intermediates

TODO: Example of creating an additional intermediate signing certificate off of our kubernetes root CA.

For now, see https://smallstep.com/docs/cli/ca/init/ (specifically, the `--root` flag)

## Exposing the CA

Beware that the CA exposes an unauthenticated endpoint that lists your configured provisioners and their encrypted private keys. For this reason, you may not want to expose it directly to the public internet.

## Uninstalling

To uninstall `autocert` completely simply delete the mutating webhook configuration, the `step` namespace and the `autocert` RBAC artifacts:

```
kubectl delete mutatingwebhookconfiguration autocert-webhook-config
kubectl delete namespace step
kubectl delete clusterrolebinding autocert-controller
kubectl delete clusterrole autocert-controller
```

Remove any namespace labels and clean up any stray secrets that `autocert` hasn't cleaned up yet:

```
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
```

Any remaining sidecar containers will go away once you remove annotations and re-deploy your workloads.