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

     1  # Setting up ExternalDNS for Services on RcodeZero
     2  
     3  This tutorial describes how to setup ExternalDNS for usage within a Kubernetes cluster using [RcodeZero Anycast DNS](https://www.rcodezero.at). Make sure to use **>=0.5.0** version of ExternalDNS for this tutorial.
     4  
     5  The following steps are required to use RcodeZero with ExternalDNS:
     6  
     7  1. Sign up for an RcodeZero account (or use an existing account).
     8  2. Add your zone to the RcodeZero DNS
     9  3. Enable the RcodeZero API, and generate an API key.
    10  4. Deploy ExternalDNS to use the RcodeZero provider.
    11  5. Verify the setup bey deploying a test services (optional)
    12  
    13  ## Creating a RcodeZero DNS zone
    14  
    15  Before records can be added to your domain name automatically, you need to add your domain name to the set of zones managed by RcodeZero. In order to add the zone, perform the following steps:
    16  
    17  1. Log in to the RcodeZero Dashboard, and move to the [Add Zone](https://my.rcodezero.at/domain/create) page.
    18  2. Select "MASTER" as domain type, and add your domain name there. Use this domain name instead of "example.com" throughout the rest of this tutorial. 
    19  
    20  Note that "SECONDARY" domains cannot be managed by ExternalDNS, because this would not allow modification of records in the zone.
    21  
    22  ## Enable the API, and create Credentials
    23  
    24  > The RcodeZero Anycast-Network is provisioned via web interface or REST-API.
    25  
    26  Enable the RcodeZero API to generate an API key on [RcodeZero API](https://my.rcodezero.at/enableapi). The API key will be added to the environment variable 'RC0_API_KEY' via one of the Manifest templates (as described below).
    27  
    28  ## Deploy ExternalDNS
    29  
    30  Connect your `kubectl` client to the cluster you want to test ExternalDNS with. Choose a Manifest from below, depending on whether or not you have RBAC enabled. Before applying it, modify the Manifest as follows:
    31  
    32  - Replace "example.com" with the domain name you added to RcodeZero.
    33  - Replace YOUR_RCODEZERO_API_KEY with the API key created above.
    34  - Replace YOUR_ENCRYPTION_KEY_STRING with a string to encrypt the TXT records
    35  
    36  ### Manifest (for clusters without RBAC enabled)
    37  
    38  ```yaml
    39  apiVersion: apps/v1
    40  kind: Deployment
    41  metadata:
    42    name: external-dns
    43  spec:
    44    strategy:
    45      type: Recreate
    46    selector:
    47      matchLabels:
    48        app: external-dns
    49    template:
    50      metadata:
    51        labels:
    52          app: external-dns
    53      spec:
    54        containers:
    55        - name: external-dns
    56          image: registry.k8s.io/external-dns/external-dns:v0.14.0
    57          args:
    58          - --source=service # ingress is also possible
    59          - --domain-filter=example.com # (optional) limit to only example.com domains; change to match the zone created above.
    60          - --provider=rcodezero
    61          - --rc0-enc-txt # (optional) encrypt TXT records; encryption key has to be provided with RC0_ENC_KEY env var.
    62          env:
    63          - name: RC0_API_KEY
    64            value: "YOUR_RCODEZERO_API_KEY"
    65          - name: RC0_ENC_VAR
    66            value: "YOUR_ENCRYPTION_KEY_STRING"
    67  ```
    68  
    69  ### Manifest (for clusters with RBAC enabled)
    70  
    71  ```yaml
    72  apiVersion: v1
    73  kind: ServiceAccount
    74  metadata:
    75    name: external-dns
    76  ---
    77  apiVersion: rbac.authorization.k8s.io/v1
    78  kind: ClusterRole
    79  metadata:
    80    name: external-dns
    81  rules:
    82  - apiGroups: [""]
    83    resources: ["services","endpoints","pods"]
    84    verbs: ["get","watch","list"]
    85  - apiGroups: ["extensions","networking.k8s.io"]
    86    resources: ["ingresses"] 
    87    verbs: ["get","watch","list"]
    88  - apiGroups: [""]
    89    resources: ["nodes"]
    90    verbs: ["list"]
    91  ---
    92  apiVersion: rbac.authorization.k8s.io/v1
    93  kind: ClusterRoleBinding
    94  metadata:
    95    name: external-dns-viewer
    96  roleRef:
    97    apiGroup: rbac.authorization.k8s.io
    98    kind: ClusterRole
    99    name: external-dns
   100  subjects:
   101  - kind: ServiceAccount
   102    name: external-dns
   103    namespace: default
   104  ---
   105  apiVersion: apps/v1
   106  kind: Deployment
   107  metadata:
   108    name: external-dns
   109  spec:
   110    strategy:
   111      type: Recreate
   112    selector:
   113      matchLabels:
   114        app: external-dns
   115    template:
   116      metadata:
   117        labels:
   118          app: external-dns
   119      spec:
   120        serviceAccountName: external-dns
   121        containers:
   122        - name: external-dns
   123          image: registry.k8s.io/external-dns/external-dns:v0.14.0
   124          args:
   125          - --source=service # ingress is also possible
   126          - --domain-filter=example.com # (optional) limit to only example.com domains; change to match the zone created above.
   127          - --provider=rcodezero
   128          - --rc0-enc-txt # (optional) encrypt TXT records; encryption key has to be provided with RC0_ENC_KEY env var.
   129          env:
   130          - name: RC0_API_KEY
   131            value: "YOUR_RCODEZERO_API_KEY"
   132          - name: RC0_ENC_VAR
   133            value: "YOUR_ENCRYPTION_KEY_STRING"
   134  ```
   135  
   136  ## Deploying an Nginx Service
   137  
   138  After you have deployed ExternalDNS with RcodeZero, you can deploy a simple service based on Nginx to test the setup. This is optional, though highly recommended before using ExternalDNS in production.
   139  
   140  Create a service file called 'nginx.yaml' with the following contents:
   141  
   142  ```yaml
   143  apiVersion: apps/v1
   144  kind: Deployment
   145  metadata:
   146    name: nginx
   147  spec:
   148    selector:
   149      matchLabels:
   150        app: nginx
   151    template:
   152      metadata:
   153        labels:
   154          app: nginx
   155      spec:
   156        containers:
   157        - image: nginx
   158          name: nginx
   159          ports:
   160          - containerPort: 80
   161  ---
   162  apiVersion: v1
   163  kind: Service
   164  metadata:
   165    name: nginx
   166    annotations:
   167      external-dns.alpha.kubernetes.io/hostname: example.com
   168      external-dns.alpha.kubernetes.io/ttl: "120" #optional
   169  spec:
   170    selector:
   171      app: nginx
   172    type: LoadBalancer
   173    ports:
   174      - protocol: TCP
   175        port: 80
   176        targetPort: 80
   177  ```
   178  
   179  Change the file as follows:
   180  
   181  - Replace the annotation of the service; use the same hostname as the RcodeZero DNS zone created above. The annotation may also be a subdomain
   182  of the DNS zone (e.g. 'www.example.com').
   183  - Set the TTL annotation of the service. A valid TTL of 120 or above must be given. This annotation is optional, and defaults to "300" if no value is given.
   184  
   185  These annotations will be used to determine what services should be registered with DNS. Removing these annotations will cause ExternalDNS to remove the corresponding DNS records.
   186  
   187  Create the Deployment and Service:
   188  
   189  ```bash
   190  $ kubectl create -f nginx.yaml
   191  ```
   192  
   193  Depending on your cloud provider, it might take a while to create an external IP for the service. Once an external IP address is assigned to the service, ExternalDNS will notice the new address and synchronize the RcodeZero DNS records accordingly.
   194  
   195  ## Verifying RcodeZero DNS records
   196  
   197  Check your [RcodeZero Configured Zones](https://my.rcodezero.at/domain) and select the respective zone name. The zone should now contain the external IP address of the service as an A record.
   198  
   199  ## Cleanup
   200  
   201  Once you have verified that ExternalDNS successfully manages RcodeZero DNS records for external services, you can delete the tutorial example as follows:
   202  
   203  ```bash
   204  $ kubectl delete -f nginx.yaml
   205  $ kubectl delete -f externaldns.yaml
   206  ```