Add certificate README.md

docs/api-types/certificate/README.md

@@ -0,0 +1,30 @@
+# Certificates
+
+cert-manager has the concept of 'Certificates' that define a desired X.509 certificate. A `Certificate` is a namespaced resource that references an `Issuer` or `ClusterIssuer` for information on how to obtain the certificate.
+
+A simple `Certificate` could be defined as:
+
+```yaml
+apiVersion: certmanager.k8s.io/v1alpha1
+kind: Certificate
+metadata:
+  name: acme-crt
+spec:
+  secretName: acme-crt-secret
+  commonName: foo.example.com
+  dnsNames:
+  - bar.example.com  
+  issuerRef:
+    name: letsencrypt-prod
+    # We can reference ClusterIssuers by changing the kind here.
+    # The default value is Issuer (i.e. a locally namespaced Issuer)
+    kind: Issuer
+```
+
+This `Certificate` will tell cert-manager to attempt to use the `Issuer` named `letsencrypt-prod` to obtain a certificate key pair for the `foo.example.com` and `bar.example.com` domains. If successful, the resulting key and certificate will be stored in a secret named `acme-crt-secret` with keys of `tls.key` and `tls.crt` respectively. This secret will live in the same namespace as the `Certificate` resource. 
+
+The `dnsNames` field specifies a list of [Subject Alternative Names][1] to be associated with the certificate. If the `commonName` field is omitted, the first element in the list will be the common name.
+
+The referenced `Issuer` must exist in the same namespace as the `Certificate`. A `Certificate` can alternatively reference a `ClusterIssuer` which is non-namespaced.
+
+  [1]: https://en.wikipedia.org/wiki/Subject_Alternative_Name