Initial commit.

Move autocert from smallstep/certificates@55cd6d0
smallstep · Jun 7, 2019 · 773bd3b · 773bd3b
1 parent 723a745
commit 773bd3b
Show file tree

Hide file tree

Showing 73 changed files with 5,058 additions and 0 deletions.
diff --git a/INSTALL.md b/INSTALL.md
@@ -0,0 +1,180 @@
+# Installing `autocert`
+
+### Prerequisites
+
+To get started you'll need [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) and a cluster running kubernetes `1.9` or later with [admission webhooks](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#admission-webhooks) enabled:
+
+```bash
+$ kubectl version --short
+Client Version: v1.13.1
+Server Version: v1.10.11
+$ kubectl api-versions | grep "admissionregistration.k8s.io/v1beta1"
+admissionregistration.k8s.io/v1beta1
+```
+
+### Install
+
+The easiest way to install `autocert` is to run:
+
+```bash
+kubectl run autocert-init -it --rm --image smallstep/autocert-init --restart Never
+```
+
+💥 installation complete.
+
+> You might want to [check out what this command does](init/autocert.sh) before running it.
+
+## Manual install
+
+To install manually you'll need to [install step](https://github.com/smallstep/cli#installing) version `0.8.3` or later.
+
+```
+$ step version
+Smallstep CLI/0.8.3 (darwin/amd64)
+Release Date: 2019-01-16 01:46 UTC
+```
+
+### Create a CA
+
+Set your `STEPPATH` to a working directory where we can stage our CA artifacts before we push them to kubernetes. You can delete this directory once installation is complete.
+
+```
+$ export STEPPATH=$(mktemp -d /tmp/step.XXX)
+$ step path
+/tmp/step.0kE
+```
+
+Run `step ca init` to generate a root certificate and CA configuration for your cluster. You'll be prompted for a password that will be used 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"
+```
+
+For older versions of `step` run this command without the flags.
+
+Add provisioning credentials for use by `autocert`. You'll be prompted for a password for `autocert`.
+
+```
+$ step ca provisioner add autocert --create
+```
+
+For older versions of `step`:
+
+* Run `step ca init` and follow prompts
+* Edit `$(step path)/config/ca.json` and change base paths to `/home/step`
+* Edit `$(step path)/config/defaults.json` to change base paths to `/home/step` and remove port from CA URL
+
+```
+$ sed -i "" "s|$(step path)|/home/step/.step|g" $(step path)/config/ca.json
+$ sed -i "" "s|$(step path)|/home/step/.step|g" $(step path)/config/defaults.json
+$ sed -i "" "s|ca.step.svc.cluster.local:4443|ca.step.svc.cluster.local|" $(step path)/config/defaults.json
+```
+
+### Install the CA in Kubernetes
+
+We'll be creating a new kubernetes namespace and setting up some RBAC rules during installation. You'll need appropriate permissions in your cluster (e.g., you may need to be cluster-admin). GKE, in particular, does not give the cluster owner these rights by default. You can give yourself cluster-admin rights on GKE by running:
+
+```bash
+kubectl create clusterrolebinding cluster-admin-binding \
+    --clusterrole cluster-admin \
+    --user $(gcloud config get-value account)
+```
+
+We'll install our CA and the `autocert` controller in the `step` namespace.
+
+```
+$ kubectl create namespace step
+```
+
+To install the CA we need to configmap the CA certificates, signing keys, and configuration artifacts. Note that key material is encrypted so we don't need to use secrets.
+
+```
+$ 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
+```
+
+But we will need to create secrets for the CA and autocert to decrypt their keys:
+
+```
+$ 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>
+```
+
+Where `<ca-password>` is the password you entered during `step ca init` and `<autocert-password>` is the password you entered during `step ca provisioner add`.
+
+Next, we'll install the CA.
+
+```
+$ kubectl apply -f https://raw.githubusercontent.com/smallstep/certificates/master/autocert/install/01-step-ca.yaml
+```
+
+Once you've done this you can delete the temporary `$STEPPATH` directory and `unset STEPPATH` (though you may want to retain it as a backup).
+
+### Install `autocert` in Kubernetes
+
+Install the `autocert` controller.
+
+```
+$ kubectl apply -f https://raw.githubusercontent.com/smallstep/certificates/master/autocert/install/02-autocert.yaml
+```
+
+Autocert creates secrets containing single-use bootstrap tokens for pods to authenticate with the CA and obtain a certificate. The tokens are automatically cleaned up after they expire. To do this, `autocert` needs permission to create and delete secrets in your cluster.
+
+If you have RBAC enabled in your cluster, apply `rbac.yaml` to give `autocert` these permissions.
+
+```
+$ kubectl apply -f https://raw.githubusercontent.com/smallstep/certificates/master/autocert/install/03-rbac.yaml
+```
+
+Finally, register the `autocert` mutation webhook with kubernetes.
+
+```
+$ cat <<EOF | kubectl apply -f -
+apiVersion: admissionregistration.k8s.io/v1beta1
+kind: MutatingWebhookConfiguration
+metadata:
+  name: autocert-webhook-config
+  labels: {app: autocert}
+webhooks:
+  - name: autocert.step.sm
+    clientConfig:
+      service:
+        name: autocert
+        namespace: step
+        path: "/mutate"
+      caBundle: $(cat $(step path)/certs/root_ca.crt | base64)
+    rules:
+      - operations: ["CREATE"]
+        apiGroups: [""]
+        apiVersions: ["v1"]
+        resources: ["pods"]
+    failurePolicy: Ignore
+    namespaceSelector:
+      matchLabels:
+        autocert.step.sm: enabled
+EOF
+```
+
+### Check your work
+
+If everything  worked you should have CA and controller pods running in the `step` namespace and your webhook configuration should be installed:
+
+```
+$ kubectl -n step get pods
+NAME                          READY   STATUS    RESTARTS   AGE
+ca-7577d7d667-vtfq5           1/1     Running   0          1m
+controller-86bd99bd96-s9zlc   1/1     Running   0          28s
+$ kubectl get mutatingwebhookconfiguration
+NAME                      CREATED AT
+autocert-webhook-config   2019-01-17T22:57:57Z
+```
+
+### Move on to usage instructions
+
+Make sure to follow the autocert usage steps at https://github.com/smallstep/certificates/tree/master/autocert#usage