update readme
This commit is contained in:
Hanfei Shen
parent
dcd294c8a1
commit
89277e219f
1
.gitignore
vendored
1
.gitignore
vendored
@ -14,3 +14,4 @@
|
||||
# Ignore the built binary
|
||||
cert-manager-webhook-dnspod
|
||||
_out
|
||||
__main__
|
||||
|
||||
150
README.md
150
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='<DNSPOD_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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user