README.md 6.6 KB
Newer Older
1
# ACME Webhook for INWX
James Munnelly's avatar
James Munnelly committed
2

Stephan Müller's avatar
Stephan Müller committed
3
4
This project provides a cert-manager ACME Webhook for [INWX](https://inwx.de/) and a corresponding helm chart.

5
The helm chart is listed at Artifact Hub in repository [smueller18](https://artifacthub.io/packages/search?page=1&repo=smueller18) at <https://artifacthub.io/packages/helm/smueller18/cert-manager-webhook-inwx>.
Stephan Müller's avatar
Stephan Müller committed
6

7
## Requirements
Stephan Müller's avatar
Stephan Müller committed
8

9
10
11
- [helm](https://helm.sh/) >= v3.0.0
- [kubernetes](https://kubernetes.io/) >= v1.18.0
- [cert-manager](https://cert-manager.io/) >= 1.0.0
James Munnelly's avatar
James Munnelly committed
12

Stephan Müller's avatar
Stephan Müller committed
13
14
15
16
17
18
19
20
21
22
23
24
## Configuration

The following table lists the configurable parameters of the cert-manager chart and their default values.

| Parameter | Description | Default |
| --------- | ----------- | ------- |
| `groupName` | Group name of the API service. | `cert-manager-webhook-inwx.smueller18.gitlab.com` |
| `credentialsSecretRef` | Name of secret where INWX credentials are stored. Used for RBAC to allow reading the secret by the service account name of webhook. | `inwx-credentials` |
| `deployment.loglevel` | Number for the log level verbosity of webhook deployment | 2 |
| `certManager.namespace` | Namespace where cert-manager is deployed to. | `cert-manager` |
| `certManager.serviceAccountName` | Service account of cert-manager installation. | `cert-manager` |
| `image.repository` | Image repository | `registry.gitlab.com/smueller18/cert-manager-webhook-inwx` |
25
| `image.tag` | Image tag | `v0.4.1` |
Stephan Müller's avatar
Stephan Müller committed
26
27
28
29
30
31
32
33
| `image.pullPolicy` | Image pull policy | `IfNotPresent` |
| `service.type` | API service type | `ClusterIP` |
| `service.port` | API service port | `443` |
| `resources` | CPU/memory resource requests/limits | `{}` |
| `nodeSelector` | Node labels for pod assignment | `{}` |
| `affinity` | Node affinity for pod assignment | `{}` |
| `tolerations` | Node tolerations for pod assignment | `[]` |

34
## Installation
James Munnelly's avatar
James Munnelly committed
35

36
### cert-manager
James Munnelly's avatar
James Munnelly committed
37

38
Follow the [instructions](https://cert-manager.io/docs/installation/) using the cert-manager documentation to install it within your cluster.
James Munnelly's avatar
James Munnelly committed
39

40
### Webhook
James Munnelly's avatar
James Munnelly committed
41

42
```bash
Stephan Müller's avatar
Stephan Müller committed
43
44
45
helm repo add smueller18 https://smueller18.gitlab.io/helm-charts
helm repo update
helm install --namespace cert-manager cert-manager-webhook-inwx smueller18/cert-manager-webhook-inwx
46
```
Stephan Müller's avatar
Stephan Müller committed
47

48
**Note**: The kubernetes resources used to install the Webhook should be deployed within the same namespace as the cert-manager.
James Munnelly's avatar
James Munnelly committed
49

50
To uninstall the webhook run
51

52
53
54
```bash
helm uninstall --namespace cert-manager cert-manager-webhook-inwx
```
James Munnelly's avatar
James Munnelly committed
55

56
57
58
## Issuer

Create a `ClusterIssuer` or `Issuer` resource as following:
59

60
```yaml
Stephan Müller's avatar
Stephan Müller committed
61
apiVersion: cert-manager.io/v1
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging
spec:
  acme:
    # The ACME server URL
    server: https://acme-staging-v02.api.letsencrypt.org/directory

    # Email address used for ACME registration
    email: mail@example.com # REPLACE THIS WITH YOUR EMAIL!!!

    # Name of a secret used to store the ACME account private key
    privateKeySecretRef:
      name: letsencrypt-staging

    solvers:
      - dns01:
          webhook:
            groupName: cert-manager-webhook-inwx.smueller18.gitlab.com
            solverName: inwx
            config:
              ttl: 300 # default 300
              sandbox: false # default false

              # prefer using secrets!
              # username: USERNAME
              # password: PASSWORD
89
              # otpKey: OTPKEY
90
91
92
93
94
95
96

              usernameSecretKeyRef:
                name: inwx-credentials
                key: username
              passwordSecretKeyRef:
                name: inwx-credentials
                key: password
97
98
99
              otpKeySecretKeyRef:
                name: inwx-credentials
                key: otpKey
100
```
James Munnelly's avatar
James Munnelly committed
101

102
### Credentials
103
104

For accessing INWX DNS provider, you need the username and password of the account. You have two choices for the configuration for the credentials, but you can also mix them. When `username` or `password` are set, these values are preferred, and the secret will not be used.
105
106
107
108

If you choose another name for the secret than `inwx-credentials`, ensure you modify the value `credentialsSecretRef` in `values.yaml`.

The secret for the example above will look like this:
109
110
111

### Without 2FA

112
113
114
115
116
117
118
119
120
```yaml
apiVersion: v1
kind: Secret
metadata:
  name: inwx-credentials
stringData:
  username: USERNAME
  password: PASSWORD
```
James Munnelly's avatar
James Munnelly committed
121

122
123
124
125
126
127
128
129
130
131
132
133
134
### With 2FA enabled

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: inwx-credentials
stringData:
  username: USERNAME
  password: PASSWORD
  otpKey: OTPKEY
```

135
136
137
138
139
### Create a certificate

Finally you can create certificates, for example:

```yaml
Stephan Müller's avatar
Stephan Müller committed
140
apiVersion: cert-manager.io/v1
141
142
143
144
145
146
147
148
149
kind: Certificate
metadata:
  name: example-cert
  namespace: cert-manager
spec:
  commonName: example.com
  dnsNames:
    - example.com
  issuerRef:
Stephan Müller's avatar
Stephan Müller committed
150
    kind: ClusterIssuer
151
152
153
    name: letsencrypt-staging
  secretName: example-cert
```
James Munnelly's avatar
James Munnelly committed
154

155
## Development
James Munnelly's avatar
James Munnelly committed
156

Stephan Müller's avatar
Stephan Müller committed
157
158
### Requirements

159
- [go](https://golang.org/) >= 1.13.0
Stephan Müller's avatar
Stephan Müller committed
160

James Munnelly's avatar
James Munnelly committed
161
162
### Running the test suite

163
164
165
166
167
1. Download test binaries
    ```bash
    scripts/fetch-test-binaries.sh
    ```

168
169
170
171
172
1. Create two test accounts (one without 2FA and one with 2FA enabled) at <https://ote.inwx.com/en/customer/signup> or use existing ones.

   1. Without 2FA

      1. Go to <https://ote.inwx.de/en/nameserver2#tab=ns> and add a new domain
173

174
      1. Copy `testdata/config.json.tpl` to `testdata/config.json` and replace username and password placeholders
175

176
      1. Copy `testdata/secret-inwx-credentials.yaml.tpl` to `testdata/secret-inwx-credentials.yaml` and replace username and password placeholders
177

178
   1. With 2FA
179

180
      1. Enable 2FA at <https://ote.inwx.com/en/setting/access#>
James Munnelly's avatar
James Munnelly committed
181

182
      1. Go to <https://ote.inwx.de/en/nameserver2#tab=ns> and add a new domain
James Munnelly's avatar
James Munnelly committed
183

184
      1. Copy `testdata/config-otp.json.tpl` to `testdata/config-otp.json` and replace username, password and OTP placeholders
James Munnelly's avatar
James Munnelly committed
185

186
      1. Copy `testdata/secret-inwx-credentials-otp.yaml.tpl` to `testdata/secret-inwx-credentials-otp.yaml` and replace username, password and OTP placeholders
Stephan Müller's avatar
Stephan Müller committed
187

188
189
190
191
1. Download dependencies
    ```bash
    go mod download
    ```
Stephan Müller's avatar
Stephan Müller committed
192

193
1. Run tests with your created domains
194
    ```bash
195
    TEST_ZONE_NAME="$YOUR_NEW_DOMAIN." TEST_ZONE_NAME_WITH_TWO_FA="$YOUR_NEW_DOMAIN_WITH_TWO_FA." go test -cover .
196
    ```
Stephan Müller's avatar
Stephan Müller committed
197

198
### Building the container image
James Munnelly's avatar
James Munnelly committed
199
200

```bash
Stephan Müller's avatar
Stephan Müller committed
201
docker build -t registry.gitlab.com/smueller18/cert-manager-webhook-inwx:master .
James Munnelly's avatar
James Munnelly committed
202
203
```

204
205
206
207
208
209
210
### Running the full suite with microk8s

Tested with Ubuntu:

```bash
sudo snap install microk8s --classic
sudo microk8s.enable dns rbac
211
sudo microk8s.kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.0.1/cert-manager.yaml
212
213
214
sudo microk8s.config > /tmp/microk8s.config
export KUBECONFIG=/tmp/microk8s.config
helm install --namespace cert-manager cert-manager-webhook-inwx deploy/cert-manager-webhook-inwx
Stephan Müller's avatar
Stephan Müller committed
215
```