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

     1  # Setting up ExternalDNS for Services on DigitalOcean
     2  
     3  This tutorial describes how to setup ExternalDNS for usage within a Kubernetes cluster using DigitalOcean DNS.
     4  
     5  Make sure to use **>=0.4.2** version of ExternalDNS for this tutorial.
     6  
     7  ## Creating a DigitalOcean DNS zone
     8  
     9  If you want to learn about how to use DigitalOcean's DNS service read the following tutorial series:
    10  
    11  [An Introduction to Managing DNS](https://www.digitalocean.com/community/tutorial_series/an-introduction-to-managing-dns), and specifically [How To Set Up a Host Name with DigitalOcean DNS](https://www.digitalocean.com/community/tutorials/how-to-set-up-a-host-name-with-digitalocean)
    12  
    13  Create a new DNS zone where you want to create your records in. Let's use `example.com` as an example here.
    14  
    15  ## Creating DigitalOcean Credentials
    16  
    17  Generate a new personal token by going to [the API settings](https://cloud.digitalocean.com/settings/api/tokens) or follow [How To Use the DigitalOcean API v2](https://www.digitalocean.com/community/tutorials/how-to-use-the-digitalocean-api-v2) if you need more information. Give the token a name and choose read and write access. The token needs to be passed to ExternalDNS so make a note of it for later use.
    18  
    19  The environment variable `DO_TOKEN` will be needed to run ExternalDNS with DigitalOcean.
    20  
    21  ## Deploy ExternalDNS
    22  
    23  Connect your `kubectl` client to the cluster you want to test ExternalDNS with.
    24  Then apply one of the following manifests file to deploy ExternalDNS.
    25  
    26  ### Manifest (for clusters without RBAC enabled)
    27  ```yaml
    28  apiVersion: apps/v1
    29  kind: Deployment
    30  metadata:
    31    name: external-dns
    32  spec:
    33    replicas: 1
    34    selector:
    35      matchLabels:
    36        app: external-dns
    37    strategy:
    38      type: Recreate
    39    template:
    40      metadata:
    41        labels:
    42          app: external-dns
    43      spec:
    44        containers:
    45        - name: external-dns
    46          image: registry.k8s.io/external-dns/external-dns:v0.14.0
    47          args:
    48          - --source=service # ingress is also possible
    49          - --domain-filter=example.com # (optional) limit to only example.com domains; change to match the zone created above.
    50          - --provider=digitalocean
    51          env:
    52          - name: DO_TOKEN
    53            value: "YOUR_DIGITALOCEAN_API_KEY"
    54  ```
    55  
    56  ### Manifest (for clusters with RBAC enabled)
    57  ```yaml
    58  apiVersion: v1
    59  kind: ServiceAccount
    60  metadata:
    61    name: external-dns
    62  ---
    63  apiVersion: rbac.authorization.k8s.io/v1
    64  kind: ClusterRole
    65  metadata:
    66    name: external-dns
    67  rules:
    68  - apiGroups: [""]
    69    resources: ["services","endpoints","pods"]
    70    verbs: ["get","watch","list"]
    71  - apiGroups: ["extensions","networking.k8s.io"]
    72    resources: ["ingresses"] 
    73    verbs: ["get","watch","list"]
    74  - apiGroups: [""]
    75    resources: ["nodes"]
    76    verbs: ["list"]
    77  ---
    78  apiVersion: rbac.authorization.k8s.io/v1
    79  kind: ClusterRoleBinding
    80  metadata:
    81    name: external-dns-viewer
    82  roleRef:
    83    apiGroup: rbac.authorization.k8s.io
    84    kind: ClusterRole
    85    name: external-dns
    86  subjects:
    87  - kind: ServiceAccount
    88    name: external-dns
    89    namespace: default
    90  ---
    91  apiVersion: apps/v1
    92  kind: Deployment
    93  metadata:
    94    name: external-dns
    95  spec:
    96    replicas: 1
    97    selector:
    98      matchLabels:
    99        app: external-dns
   100    strategy:
   101      type: Recreate
   102    template:
   103      metadata:
   104        labels:
   105          app: external-dns
   106      spec:
   107        serviceAccountName: external-dns
   108        containers:
   109        - name: external-dns
   110          image: registry.k8s.io/external-dns/external-dns:v0.14.0
   111          args:
   112          - --source=service # ingress is also possible
   113          - --domain-filter=example.com # (optional) limit to only example.com domains; change to match the zone created above.
   114          - --provider=digitalocean
   115          env:
   116          - name: DO_TOKEN
   117            value: "YOUR_DIGITALOCEAN_API_KEY"
   118  ```
   119  
   120  
   121  ## Deploying an Nginx Service
   122  
   123  Create a service file called 'nginx.yaml' with the following contents:
   124  
   125  ```yaml
   126  apiVersion: apps/v1
   127  kind: Deployment
   128  metadata:
   129    name: nginx
   130  spec:
   131    replicas: 1
   132    selector:
   133      matchLabels:
   134        app: nginx
   135    template:
   136      metadata:
   137        labels:
   138          app: nginx
   139      spec:
   140        containers:
   141        - image: nginx
   142          name: nginx
   143          ports:
   144          - containerPort: 80
   145  ---
   146  apiVersion: v1
   147  kind: Service
   148  metadata:
   149    name: nginx
   150    annotations:
   151      external-dns.alpha.kubernetes.io/hostname: my-app.example.com
   152  spec:
   153    selector:
   154      app: nginx
   155    type: LoadBalancer
   156    ports:
   157      - protocol: TCP
   158        port: 80
   159        targetPort: 80
   160  ```
   161  
   162  Note the annotation on the service; use the same hostname as the DigitalOcean DNS zone created above.
   163  
   164  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.
   165  
   166  Create the deployment and service:
   167  
   168  ```console
   169  $ kubectl create -f nginx.yaml
   170  ```
   171  
   172  Depending where you run your service it can take a little while for your cloud provider to create an external IP for the service.
   173  
   174  Once the service has an external IP assigned, ExternalDNS will notice the new service IP address and synchronize the DigitalOcean DNS records.
   175  
   176  ## Verifying DigitalOcean DNS records
   177  
   178  Check your [DigitalOcean UI](https://cloud.digitalocean.com/networking/domains) to view the records for your DigitalOcean DNS zone.
   179  
   180  Click on the zone for the one created above if a different domain was used.
   181  
   182  This should show the external IP address of the service as the A record for your domain.
   183  
   184  ## Cleanup
   185  
   186  Now that we have verified that ExternalDNS will automatically manage DigitalOcean DNS records, we can delete the tutorial's example:
   187  
   188  ```
   189  $ kubectl delete service -f nginx.yaml
   190  $ kubectl delete service -f externaldns.yaml
   191  ```
   192  
   193  ## Advanced Usage
   194  
   195  ### API Page Size
   196  
   197  If you have a large number of domains and/or records within a domain, you may encounter API
   198  rate limiting because of the number of API calls that external-dns must make to the DigitalOcean API to retrieve
   199  the current DNS configuration during every reconciliation loop. If this is the case, use the 
   200  `--digitalocean-api-page-size` option to increase the size of the pages used when querying the DigitalOcean API.
   201  (Note: external-dns uses a default of 50.)