From 89277e219fd0267e9a8b332220bbef273b399ae2 Mon Sep 17 00:00:00 2001 From: Hanfei Shen Date: Sat, 15 Jun 2019 22:43:18 +0800 Subject: [PATCH] update readme --- .gitignore | 1 + README.md | 150 ++++++++++++++++++++++++++++++++++++++++++----------- 2 files changed, 122 insertions(+), 29 deletions(-) diff --git a/.gitignore b/.gitignore index 005aed9..1deae7e 100644 --- a/.gitignore +++ b/.gitignore @@ -14,3 +14,4 @@ # Ignore the built binary cert-manager-webhook-dnspod _out +__main__ diff --git a/README.md b/README.md index dbf5a42..e8440f3 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,125 @@ -# ACME webhook example +# DNSPod Webhook for Cert Manager -The ACME issuer type supports an optional 'webhook' solver, which can be used -to implement custom DNS01 challenge solving logic. +This is a webhook solver for [DNSPod](https://www.dnspod.cn). -This is useful if you need to use cert-manager with a DNS provider that is not -officially supported in cert-manager core. +## Prerequisites -## Why not in core? +* [cert-manager](https://github.com/jetstack/cert-manager): *tested with 0.8.0* + - [Installing on Kubernetes](https://docs.cert-manager.io/en/release-0.8/getting-started/install/kubernetes.html) -As the project & adoption has grown, there has been an influx of DNS provider -pull requests to our core codebase. As this number has grown, the test matrix -has become un-maintainable and so, it's not possible for us to certify that -providers work to a sufficient level. +## Installation -By creating this 'interface' between cert-manager and DNS providers, we allow -users to quickly iterate and test out new integrations, and then packaging -those up themselves as 'extensions' to cert-manager. +```console +$ helm install --name cert-manager-webhook-dnspod ./deploy/example-webhook +``` -We can also then provide a standardised 'testing framework', or set of -conformance tests, which allow us to validate the a DNS provider works as -expected. +## Issuer -## Creating your own webhook +1. Generate API ID and API Token from DNSPod (https://support.dnspod.cn/Kb/showarticle/tsid/227/) +2. Create secret to store the API Token +```console +$ kubectl --namespace cert-manager create secret generic \ + dnspod-credentials --from-literal=api-token='' +``` -Webhook's themselves are deployed as Kubernetes API services, in order to allow -administrators to restrict access to webhooks with Kubernetes RBAC. +3. Grant permission for service-account to get the secret +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: cert-manager-webhook-dnspod:secret-reader +rules: +- apiGroups: [""] + resources: ["secrets"] + resourceNames: ["dnspod-credentials"] + verbs: ["get", "watch"] +--- +apiVersion: rbac.authorization.k8s.io/v1beta1 +kind: RoleBinding +metadata: + name: cert-manager-webhook-dnspod:secret-reader +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: cert-manager-webhook-dnspod:secret-reader +subjects: + - apiGroup: "" + kind: ServiceAccount + name: cert-manager-webhook-dnspod +``` -This is important, as otherwise it'd be possible for anyone with access to your -webhook to complete ACME challenge validations and obtain certificates. +4. Create a staging issuer *Optional* +```yaml +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 -To make the set up of these webhook's easier, we provide a template repository -that can be used to get started quickly. + # Email address used for ACME registration + email: user@example.com # REPLACE THIS WITH YOUR EMAIL!!! -### Creating your own repository + # Name of a secret used to store the ACME account private key + privateKeySecretRef: + name: letsencrypt-staging -### Running the test suite + solvers: + - dns01: + webhook: + groupName: example.com # REPLACE THIS TO YOUR GROUP + solverName: dnspod + config: + apiID: 12345 # REPLACE WITH API ID FROM DNSPOD!!! + apiTokenSecretRef: + key: api-token + name: dnspod-credentials +``` + +5. Create a production issuer +```yaml +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 # REPLACE THIS WITH YOUR EMAIL!!! + + # Name of a secret used to store the ACME account private key + privateKeySecretRef: + name: letsencrypt-prod + + solvers: + - dns01: + webhook: + groupName: example.com # REPLACE THIS TO YOUR GROUP + solverName: dnspod + config: + apiID: 12345 # REPLACE WITH API ID FROM DNSPOD!!! + apiTokenSecretRef: + key: api-token + name: dnspod-credentials +``` + +## Certificate + +1. Issue a certificate +```yaml +#TODO +``` + +### Automatically creating Certificates for Ingress resources + +See [this](https://docs.cert-manager.io/en/latest/tasks/issuing-certificates/ingress-shim.html). + +## Development All DNS providers **must** run the DNS01 provider conformance testing suite, else they will have undetermined behaviour when used with cert-manager. @@ -44,11 +129,18 @@ DNS01 webhook.** An example Go test file has been provided in [main_test.go](). -You can run the test suite with: +Before you can run the test suite, you need to download the test binaries: + +```console +$ mkdir __main__ +$ wget -O- https://storage.googleapis.com/kubebuilder-tools/kubebuilder-tools-1.14.1-darwin-amd64.tar.gz | tar x - +$ mv kubebuilder __main__/hack +``` + +Then modify `testdata/my-custom-solver/config.json` to setup the configs. + +Now you can run the test suite with: ```bash $ TEST_ZONE_NAME=example.com go test . ``` - -The example file has a number of areas you must fill in and replace with your -own options in order for tests to pass.