Merge pull request #1055 from heckj/quickstart-guide

Add quick-start guide for nginx ingress controller

.gitignore

@@ -5,4 +5,5 @@
 /ingress-shim
 /hack/build/dockerfiles/cert-manager-*_*_*
 .vscode
+.venv
 bazel-*

README.md

@@ -28,6 +28,15 @@ Documentation for cert-manager can be found at [cert-manager.readthedocs.io](htt
 Please make sure to select the correct version of the documentation to view on
 the bottom left of the page.
 
+For the common use-case of automatically issuing TLS certificates to
+Ingress resources, aka a [kube-lego](https://github.com/jetstack/kube-lego)
+replacement, see the [cert-manager nginx ingress quick start
+guide](docs/tutorials/quick-start/index.rst).
+
+See [Getting started](https://cert-manager.readthedocs.io/en/latest/getting-started/)
+within the [documentation](https://cert-manager.readthedocs.io/en/latest/)
+for installation instructions.
+
 ## Troubleshooting
 
 If you encounter any issues whilst using cert-manager, we have a number of places you

docs/devel/generate-docs.rst

@@ -1,6 +1,6 @@
-=====================
+========================
 Generating Documentation
-=====================
+========================
 
 The documentation is generated from `reStructured Text`_ by `Sphinx`_
 (via `Read The Docs`_). If you're unfamiliar with `reStructured Text`_,
@@ -28,6 +28,10 @@ You can generate the documentation locally with the following command:
 This will create documentation in the ``_build`` directory which you can
 open with your browser.
 
+.. code-block: shell
+
+   open _build/html/index.html
+
 Note that you do not need to add these files to your git client, as
 *Read The Docs* will generate the HTML on the fly.
 

docs/devel/index.rst

@@ -9,3 +9,4 @@ Development documentation
    dns01-providers
    dco-sign-off
    release-process
+   generate-docs

docs/tutorials/acme/migrating-from-kube-lego.rst

@@ -54,7 +54,7 @@ deployment YAMLs, a command like so should do:
 
    $ kubectl scale deployment kube-lego \
        --namespace kube-lego \
-       --replicas=0 \
+       --replicas=0
 
 You can then verify your kube-lego pod is no longer running with:
 

docs/tutorials/index.rst

@@ -8,6 +8,7 @@ cert-manager.
 .. toctree::
    :maxdepth: 2
 
+   quick-start/index
    acme/index
    ca/index
    vault/index

docs/tutorials/quick-start/echoserver/deployment.yaml → docs/tutorials/quick-start/example/deployment.yaml

@@ -1,18 +1,17 @@
 apiVersion: extensions/v1beta1
 kind: Deployment
 metadata:
-  name: echoserver
-  namespace: default
+  name: kuard
 spec:
   replicas: 1
   template:
     metadata:
       labels:
-        app: echoserver
+        app: kuard
     spec:
       containers:
-      - image: gcr.io/google_containers/echoserver:1.0
+      - image: gcr.io/kuar-demo/kuard-amd64:1
         imagePullPolicy: Always
-        name: echoserver
+        name: kuard
         ports:
         - containerPort: 8080

docs/tutorials/quick-start/example/ingress-tls-final.yaml

@@ -0,0 +1,22 @@
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+  name: kuard
+  annotations:
+    kubernetes.io/ingress.class: "nginx"    
+    certmanager.k8s.io/issuer: "letsencrypt-prod"
+    certmanager.k8s.io/acme-challenge-type: http01
+
+spec:
+  tls:
+  - hosts:
+    - example.example.com
+    secretName: quickstart-example-tls
+  rules:
+  - host: example.example.com
+    http:
+      paths:
+      - path: /
+        backend:
+          serviceName: kuard
+          servicePort: 80

docs/tutorials/quick-start/example/ingress-tls.yaml

@@ -0,0 +1,22 @@
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+  name: kuard
+  annotations:
+    kubernetes.io/ingress.class: "nginx"    
+    certmanager.k8s.io/issuer: "letsencrypt-staging"
+    certmanager.k8s.io/acme-challenge-type: http01
+
+spec:
+  tls:
+  - hosts:
+    - example.example.com
+    secretName: quickstart-example-tls
+  rules:
+  - host: example.example.com
+    http:
+      paths:
+      - path: /
+        backend:
+          serviceName: kuard
+          servicePort: 80

docs/tutorials/quick-start/example/ingress.yaml

@@ -0,0 +1,22 @@
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+  name: kuard
+  annotations:
+    kubernetes.io/ingress.class: "nginx"    
+    #certmanager.k8s.io/issuer: "letsencrypt-staging"
+    #certmanager.k8s.io/acme-challenge-type: http01
+
+spec:
+  tls:
+  - hosts:
+    - example.example.com
+    secretName: quickstart-example-tls
+  rules:
+  - host: example.example.com
+    http:
+      paths:
+      - path: /
+        backend:
+          serviceName: kuard
+          servicePort: 80

docs/tutorials/quick-start/example/production-issuer.yaml

@@ -0,0 +1,15 @@
+   apiVersion: certmanager.k8s.io/v1alpha1
+   kind: Issuer
+   metadata:
+     name: letsencrypt-prod
+   spec:
+     acme:
+       # The ACME server URL
+       server: https://acme-v02.api.letsencrypt.org/directory
+       # Email address used for ACME registration
+       email: user@example.com
+       # Name of a secret used to store the ACME account private key
+       privateKeySecretRef:
+         name: letsencrypt-prod
+       # Enable the HTTP-01 challenge provider
+       http01: {}

docs/tutorials/quick-start/echoserver/service.yaml → docs/tutorials/quick-start/example/service.yaml

@@ -1,12 +1,11 @@
 apiVersion: v1
 kind: Service
 metadata:
-  name: echoserver
-  namespace: default
+  name: kuard
 spec:
   ports:
   - port: 80
     targetPort: 8080
     protocol: TCP
   selector:
-    app: echoserver
+    app: kuard

docs/tutorials/quick-start/example/staging-issuer.yaml

@@ -0,0 +1,15 @@
+   apiVersion: certmanager.k8s.io/v1alpha1
+   kind: Issuer
+   metadata:
+     name: letsencrypt-staging
+   spec:
+     acme:
+       # The ACME server URL
+       server: https://acme-staging-v02.api.letsencrypt.org/directory
+       # Email address used for ACME registration
+       email: user@example.com
+       # Name of a secret used to store the ACME account private key
+       privateKeySecretRef:
+         name: letsencrypt-staging
+       # Enable the HTTP-01 challenge provider
+       http01: {}