Update documentation

docs/README.md

@@ -0,0 +1,19 @@
+# cert-manager documentation
+
+This is the extended documentation page for cert-manager, containing detailed
+specification of API types, user guides, and developer documentation.
+
+It is split into these three sections for easier navigation.
+
+## API types
+
+* [Issuer](api-types/issuer/)
+* Certificate (coming soon)
+
+## User guides
+
+* Coming soon
+
+## Developer docs
+
+Developer documentation can be found in the `devel/` directory (coming soon).

docs/acme-issuer.yaml

@@ -1,36 +0,0 @@
-apiVersion: certmanager.k8s.io/v1alpha1
-kind: Issuer
-metadata:
-  name: letsencrypt-staging
-spec:
-  acme:
-    # The ACME server URL
-    server: https://acme-staging.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
-    privateKey: letsncrypt-staging
-    # ACME dns-01 provider configurations
-    dns-01:
-      # Here we define a list of DNS-01 providers that can solve DNS challenges
-      providers:
-      # We define a provider named 'clouddns', with configuration for the
-      # clouddns challenge provider.
-      - name: clouddns
-        clouddns:
-          # A secretKeyRef to a the google cloud json service account
-          serviceAccount:
-            name: clouddns-service-account
-            key: service-account.json
-          # The project in which to update the DNS zone
-          project: gcloud-project
-      # We define a provider named 'cloudflare', with configuration for the
-      # cloudflare challenge provider.
-      - name: cloudflare
-        cloudflare:
-          # A secretKeyRef to a the cloudflare api key
-          apiKey:
-            name: cloudflare-config
-            key: api-key
-          # The cloudflare user account email
-          email: cloudflare-user@example.com

docs/api-types/issuer/README.md

@@ -0,0 +1,47 @@
+# Issuers
+
+cert-manager has the concept of 'Issuers' that define a source of X.509
+certificates, including any configuration required for that source.
+
+An example of an Issuer is ACME. A simple ACME issuer could be defined as:
+
+```yaml
+kind: Issuer
+metadata:
+  name: letsencrypt-prod
+  namespace: edge-services
+spec:
+  acme:
+    # The ACME server URL
+    server: https://acme-v01.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
+    privateKey: letsncrypt-prod
+```
+
+This is the simplest of ACME issuers - it specifies no DNS-01 challenge
+providers. HTTP-01 validation can be performed through using Ingress
+resources without any additional configuration on the Issuer resource.
+
+## Namespacing
+
+An Issuer is a namespaced resource, and it is not possible to issue
+certificates from an Issuer in a different namespace. This means you will need
+to create an Issuer in each namespace you wish to obtain Certificates in.
+
+If you want to create a single issuer than can be consumed in multiple
+namespaces, you should consider creating a `ClusterIssuer` resource. This is
+almost identical to the `Issuer` resource, however is non-namespaced and so can
+be great at the cluster level.
+
+## Supported issuer types
+
+cert-manager has been designed to support pluggable Issuer backends. Below is
+a list of the currently supported issuers and a link to the spec for their
+definition.
+
+* [ACME](spec.md#acme-configuration)
+* [CA](spec.md#ca-configuration)
+
+This list will be kept up to date as new issuers are added.

docs/api-types/issuer/spec.md

@@ -0,0 +1,133 @@
+# Issuer spec
+
+The full spec for an Issuer can be seen in [types.go](../../..//pkg/apis/certmanager/v1alpha1/types.go).
+It contains the most up to date copy of the Issuer specification, and should
+be used as the canonical source for the API schema.
+
+Issuers are a representation of some source of signed certificates in the
+cert-manager API. Each Issuer is of one, and only one type. The type of an
+issuer is denoted by which field it specifies in its spec, such as `spec.acme`
+for the ACME issuer, or `spec.ca` for the CA based issuer.
+
+For example, to a basic ACME Issuer can be configured like so:
+
+```yaml
+apiVersion: certmanager.k8s.io/v1alpha1
+kind: Issuer
+metadata:
+  name: letsencrypt-prod
+spec:
+  acme:
+    server: https://acme-v01.api.letsencrypt.org/directory
+    email: user@example.com
+    # Name of a secret used to store the ACME account private key
+    privateKey: letsncrypt-prod
+```
+
+## ACME configuration
+
+In order to use the ACME provider, there are a number of required fields.
+For your ACME issuer to support the various ACME challenge mechanisms, you may
+need to provide some additional configuration on your resource, such as
+configuring credentials for a DNS provider.
+
+### ACME issuer HTTP01 configuration
+
+The ACME issuer does not require any additional configuration in order to
+support HTTP01 challenge validation. All valid ACME issuers are able to issue
+certificates validated with HTTP01 by creating or manipulating Ingress
+resources in the Kubernetes API server. The installed ingress controller will
+then configure routes to solve ACME challenges automatically.
+
+### ACME issuer with no configured DNS providers
+
+Below is an ACME issuer that has been configured to only allow issuing
+certificates validated with HTTP01 challenges. A new ACME account will be
+registered if required, using a private key stored in a Secret in the same
+namespace as the Issuer, named `example-issuer-account-key`. It will use the
+provided email address on the registration, and register the account with the
+listed ACME server (the letsencrypt staging server in this case).
+
+```yaml
+apiVersion: certmanager.k8s.io
+kind: Issuer
+metadata:
+  name: example-issuer
+spec:
+  acme:
+    email: user@example.com
+    server: https://acme-staging.api.letsencrypt.org/directory
+    privateKey: example-issuer-account-key
+```
+
+### ACME issuer DNS provider configuration
+
+The ACME issuer can also contain DNS provider configuration, which can be used
+by Certificates using this Issuer in order to validate DNS01 challenge
+requests:
+
+```yaml
+apiVersion: certmanager.k8s.io
+kind: Issuer
+metadata:
+  name: example-issuer
+spec:
+  acme:
+    email: user@example.com
+    server: https://acme-staging.api.letsencrypt.org/directory
+    privateKey: example-issuer-account-key
+    dns-01:
+      providers:
+      - name: prod-clouddns
+        clouddns:
+          serviceAccount:
+            name: prod-clouddns-svc-acct-secret
+            key: service-account.json
+```
+
+Each issuer can specify multiple different DNS01 challenge providers, and
+it is also possible to have multiple instances of the same DNS provider on a
+single Issuer (e.g. two clouddns accounts could be set, each with their own
+name).
+
+#### Supported DNS01 challenge providers
+
+A number of different DNS providers are supported for the ACME issuer. Below is
+a listing of them all, with an example block of configuration:
+
+##### Google CloudDNS
+
+```yaml
+clouddns:
+  serviceAccount:
+    name: prod-clouddns-svc-acct-secret
+    key: service-account.json
+```
+
+##### Amazon Route53
+
+```yaml
+route53:
+  accessKeyID: AKIAIOSFODNN7EXAMPLE
+  region: eu-west-1
+  secretAccessKey:
+    name: prod-route53-credentials-secret
+    key: secret-access-key
+```
+
+##### Cloudflare
+
+```yaml
+cloudflare:
+  email: my-cloudflare-acc@example.com
+  secretAccessKey:
+    name: cloudflare-api-key-secret
+    key: api-key
+```
+
+## CA Configuration
+
+CA Issuers issue certificates signed from a X509 signing keypair, stored in a
+secret in the Kubernetes API server.
+
+

docs/examples/acme-cert.yaml

@@ -3,16 +3,16 @@
 apiVersion: certmanager.k8s.io/v1alpha1
 kind: Certificate
 metadata:
-  name: example-cert
+  name: cm-http-nginx-k8s-group
 spec:
-  secretName: example-cert
+  secretName: cm-http-nginx-k8s-group
   issuer: letsencrypt-staging
   domains:
   - cm-http-nginx.k8s.group
   - cm-http-nginx2.k8s.group
   - cm-http-gce.k8s.group
-  - cm-dns-clouddns.k8s.group
-  - cm-dns-cloudflare.k8s.group
+  - cm-http-clouddns.k8s.group
+  - cm-http-cloudflare.k8s.group
   acme:
     config:
     - http-01:

docs/examples/acme-issuer.yaml

@@ -0,0 +1,14 @@
+apiVersion: certmanager.k8s.io/v1alpha1
+kind: Issuer
+metadata:
+  name: letsencrypt-prod
+  namespace: skeleton-review
+spec:
+  acme:
+    # The ACME server URL
+    server: https://acme-v01.api.letsencrypt.org/directory
+    # Email address used for ACME registration
+    email: james+workshops@jetstack.io
+    # Name of a secret used to store the ACME account private key
+    privateKey: letsncrypt-prod
+    # ACME dns-01 provider configurations

docs/examples/ca-cert.yaml

@@ -0,0 +1,11 @@
+## Example Certificate that uses multiple challenge mechanisms to obtain
+## a SAN certificate for multiple domains from the letsencrypt-staging issuer.
+apiVersion: certmanager.k8s.io/v1alpha1
+kind: Certificate
+metadata:
+  name: test-ca-crt
+spec:
+  secretName: test-ca-crt
+  issuer: ca-issuer
+  domains:
+  - cert-manager.k8s.io

docs/examples/ca-issuer.yaml

@@ -0,0 +1,8 @@
+apiVersion: certmanager.k8s.io/v1alpha1
+kind: Issuer
+metadata:
+  name: ca-issuer
+spec:
+  ca:
+    secretRef:
+      name: ca-key-pair

docs/rbac.yaml

@@ -1,30 +0,0 @@
-apiVersion: rbac.authorization.k8s.io/v1beta1
-kind: ClusterRole
-metadata:
-  name: cert-manager
-rules:
-- apiGroups: ["certmanager.k8s.io"]
-  resources: ["certificates", "issuers"]
-  verbs: ["*"]
-- apiGroups: [""]
-  resources: ["secrets", "events", "endpoints", "services"]
-  verbs: ["*"]
-- apiGroups: ["extensions"]
-  resources: ["ingresses"]
-  verbs: ["*"]
-- apiGroups: ["batch"]
-  resources: ["jobs"]
-  verbs: ["list", "watch", "create", "delete", "get"]
----
-apiVersion: rbac.authorization.k8s.io/v1beta1
-kind: ClusterRoleBinding
-metadata:
-  name: cert-manager-binding
-roleRef:
-  apiGroup: rbac.authorization.k8s.io
-  kind: ClusterRole
-  name: cert-manager
-subjects:
-- namespace: default
-  kind: ServiceAccount
-  name: default