diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..180e3170b --- /dev/null +++ b/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). diff --git a/docs/acme-issuer.yaml b/docs/acme-issuer.yaml deleted file mode 100644 index 7b611ab30..000000000 --- a/docs/acme-issuer.yaml +++ /dev/null @@ -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 diff --git a/docs/api-types/issuer/README.md b/docs/api-types/issuer/README.md new file mode 100644 index 000000000..d6f5943f8 --- /dev/null +++ b/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. diff --git a/docs/api-types/issuer/spec.md b/docs/api-types/issuer/spec.md new file mode 100644 index 000000000..3b9ea2bcf --- /dev/null +++ b/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. + + diff --git a/docs/acme-cert.yaml b/docs/examples/acme-cert.yaml similarity index 85% rename from docs/acme-cert.yaml rename to docs/examples/acme-cert.yaml index 12e212f08..fb1c204f1 100644 --- a/docs/acme-cert.yaml +++ b/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: diff --git a/docs/examples/acme-issuer.yaml b/docs/examples/acme-issuer.yaml new file mode 100644 index 000000000..5cf22723b --- /dev/null +++ b/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 diff --git a/docs/examples/ca-cert.yaml b/docs/examples/ca-cert.yaml new file mode 100644 index 000000000..654e30be5 --- /dev/null +++ b/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 diff --git a/docs/examples/ca-issuer.yaml b/docs/examples/ca-issuer.yaml new file mode 100644 index 000000000..a8f2ced4b --- /dev/null +++ b/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 diff --git a/docs/cert-manager.yaml b/docs/examples/cert-manager.yaml similarity index 100% rename from docs/cert-manager.yaml rename to docs/examples/cert-manager.yaml diff --git a/docs/crd.yaml b/docs/examples/crd.yaml similarity index 100% rename from docs/crd.yaml rename to docs/examples/crd.yaml diff --git a/docs/tpr.yaml b/docs/examples/tpr.yaml similarity index 100% rename from docs/tpr.yaml rename to docs/examples/tpr.yaml diff --git a/docs/rbac.yaml b/docs/rbac.yaml deleted file mode 100644 index 7187e0f68..000000000 --- a/docs/rbac.yaml +++ /dev/null @@ -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 diff --git a/docs/user-guides/README.md b/docs/user-guides/README.md new file mode 100644 index 000000000..e69de29bb