sigs.k8s.io/external-dns@v0.14.1/docs/tutorials/dnsimple.md (about)

     1  # Setting up ExternalDNS for Services on DNSimple
     2  
     3  
     4  This tutorial describes how to setup ExternalDNS for usage with DNSimple.
     5  
     6  Make sure to use **>=0.4.6** version of ExternalDNS for this tutorial.
     7  
     8  ## Created a DNSimple API Access Token
     9  
    10  A DNSimple API access token can be acquired by following the [provided documentation from DNSimple](https://support.dnsimple.com/articles/api-access-token/)
    11  
    12  The environment variable `DNSIMPLE_OAUTH` must be set to the API token generated for to run ExternalDNS with DNSimple.
    13  
    14  ## Deploy ExternalDNS
    15  
    16  Connect your `kubectl` client to the cluster you want to test ExternalDNS with.
    17  Then apply one of the following manifests file to deploy ExternalDNS.
    18  
    19  ### Manifest (for clusters without RBAC enabled)
    20  ```yaml
    21  apiVersion: apps/v1
    22  kind: Deployment
    23  metadata:
    24    name: external-dns
    25  spec:
    26    strategy:
    27      type: Recreate
    28    selector:
    29      matchLabels:
    30        app: external-dns
    31    template:
    32      metadata:
    33        labels:
    34          app: external-dns
    35      spec:
    36        containers:
    37        - name: external-dns
    38          image: registry.k8s.io/external-dns/external-dns:v0.14.0
    39          args:
    40          - --source=service
    41          - --domain-filter=example.com # (optional) limit to only example.com domains; change to match the zone you create in DNSimple.
    42          - --provider=dnsimple
    43          - --registry=txt
    44          env:
    45          - name: DNSIMPLE_OAUTH
    46            value: "YOUR_DNSIMPLE_API_KEY"
    47  ```
    48  
    49  ### Manifest (for clusters with RBAC enabled)
    50  
    51  ```yaml
    52  apiVersion: v1
    53  kind: ServiceAccount
    54  metadata:
    55    name: external-dns
    56  ---
    57  apiVersion: rbac.authorization.k8s.io/v1
    58  kind: ClusterRole
    59  metadata:
    60    name: external-dns
    61  rules:
    62  - apiGroups: [""]
    63    resources: ["services","endpoints","pods"]
    64    verbs: ["get","watch","list"]
    65  - apiGroups: ["extensions","networking.k8s.io"]
    66    resources: ["ingresses"]
    67    verbs: ["get","watch","list"]
    68  - apiGroups: [""]
    69    resources: ["nodes"]
    70    verbs: ["list"]
    71  ---
    72  apiVersion: rbac.authorization.k8s.io/v1
    73  kind: ClusterRoleBinding
    74  metadata:
    75    name: external-dns-viewer
    76  roleRef:
    77    apiGroup: rbac.authorization.k8s.io
    78    kind: ClusterRole
    79    name: external-dns
    80  subjects:
    81  - kind: ServiceAccount
    82    name: external-dns
    83    namespace: default
    84  ---
    85  apiVersion: apps/v1
    86  kind: Deployment
    87  metadata:
    88    name: external-dns
    89  spec:
    90    strategy:
    91      type: Recreate
    92    selector:
    93      matchLabels:
    94        app: external-dns
    95    template:
    96      metadata:
    97        labels:
    98          app: external-dns
    99      spec:
   100        serviceAccountName: external-dns
   101        containers:
   102        - name: external-dns
   103          image: registry.k8s.io/external-dns/external-dns:v0.14.0
   104          args:
   105          - --source=service
   106          - --domain-filter=example.com # (optional) limit to only example.com domains; change to match the zone you create in DNSimple.
   107          - --provider=dnsimple
   108          - --registry=txt
   109          env:
   110          - name: DNSIMPLE_OAUTH
   111            value: "YOUR_DNSIMPLE_API_KEY"
   112  ```
   113  
   114  
   115  ## Deploying an Nginx Service
   116  
   117  Create a service file called 'nginx.yaml' with the following contents:
   118  
   119  ```yaml
   120  apiVersion: apps/v1
   121  kind: Deployment
   122  metadata:
   123    name: nginx
   124  spec:
   125    selector:
   126      matchLabels:
   127        app: nginx
   128    template:
   129      metadata:
   130        labels:
   131          app: nginx
   132      spec:
   133        containers:
   134        - image: nginx
   135          name: nginx
   136          ports:
   137          - containerPort: 80
   138  ---
   139  apiVersion: v1
   140  kind: Service
   141  metadata:
   142    name: nginx
   143    annotations:
   144      external-dns.alpha.kubernetes.io/hostname: validate-external-dns.example.com
   145  spec:
   146    selector:
   147      app: nginx
   148    type: LoadBalancer
   149    ports:
   150      - protocol: TCP
   151        port: 80
   152        targetPort: 80
   153  ```
   154  
   155  Note the annotation on the service; use the same hostname as the DNSimple DNS zone created above. The annotation may also be a subdomain
   156  of the DNS zone (e.g. 'www.example.com').
   157  
   158  ExternalDNS uses this annotation to determine what services should be registered with DNS.  Removing the annotation will cause ExternalDNS to remove the corresponding DNS records.
   159  
   160  Create the deployment and service:
   161  
   162  ```sh
   163  $ kubectl create -f nginx.yaml
   164  ```
   165  
   166  Depending where you run your service it can take a little while for your cloud provider to create an external IP for the service. Check the status by running
   167  `kubectl get services nginx`.  If the `EXTERNAL-IP` field shows an address, the service is ready to be accessed externally.
   168  
   169  Once the service has an external IP assigned, ExternalDNS will notice the new service IP address and synchronize
   170  the DNSimple DNS records.
   171  
   172  ## Verifying DNSimple DNS records
   173  
   174  ### Getting your DNSimple Account ID
   175  
   176  If you do not know your DNSimple account ID it can be acquired using the [whoami](https://developer.dnsimple.com/v2/identity/#whoami) endpoint from the DNSimple Identity API
   177  
   178  ```sh
   179  curl -H "Authorization: Bearer $DNSIMPLE_ACCOUNT_TOKEN" \
   180      -H 'Accept: application/json' \
   181      https://api.dnsimple.com/v2/whoami
   182  {
   183    "data": {
   184      "user": null,
   185      "account": {
   186        "id": 1,
   187        "email": "example-account@example.com",
   188        "plan_identifier": "dnsimple-professional",
   189        "created_at": "2015-09-18T23:04:37Z",
   190        "updated_at": "2016-06-09T20:03:39Z"
   191      }
   192    }
   193  }
   194  ```
   195  
   196  ### Looking at the DNSimple Dashboard
   197  
   198  You can view your DNSimple Record Editor at https://dnsimple.com/a/YOUR_ACCOUNT_ID/domains/example.com/records. Ensure you substitute the value `YOUR_ACCOUNT_ID` with the ID of your DNSimple account and `example.com` with the correct domain that you used during validation.
   199  
   200  ### Using the DNSimple Zone Records API
   201  
   202  This approach allows for you to use the DNSimple [List records for a zone](https://developer.dnsimple.com/v2/zones/records/#listZoneRecords) endpoint to verify the creation of the A and TXT record. Ensure you substitute the value `YOUR_ACCOUNT_ID` with the ID of your DNSimple account and `example.com` with the correct domain that you used during validation.
   203  
   204  ```sh
   205  curl -H "Authorization: Bearer $DNSIMPLE_ACCOUNT_TOKEN" \
   206      -H 'Accept: application/json' \
   207      'https://api.dnsimple.com/v2/YOUR_ACCOUNT_ID/zones/example.com/records&name=validate-external-dns'
   208  ```
   209  
   210  ## Clean up
   211  
   212  Now that we have verified that ExternalDNS will automatically manage DNSimple DNS records, we can delete the tutorial's example:
   213  
   214  ```sh
   215  $ kubectl delete -f nginx.yaml
   216  $ kubectl delete -f externaldns.yaml
   217  ```
   218  
   219  ### Deleting Created Records
   220  
   221  The created records can be deleted using the record IDs from the verification step and the [Delete a zone record](https://developer.dnsimple.com/v2/zones/records/#deleteZoneRecord) endpoint.