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

     1  # Setting up ExternalDNS for Services on UltraDNS
     2  
     3  This tutorial describes how to setup ExternalDNS for usage within a Kubernetes cluster using UltraDNS.
     4  
     5  For this tutorial, please make sure that you are using a version **> 0.7.2** of ExternalDNS.
     6  
     7  ## Managing DNS with UltraDNS
     8  
     9  If you would like to read-up on the UltraDNS service, you can find additional details here: [Introduction to UltraDNS](https://docs.ultradns.com/)
    10  
    11  Before proceeding, please create a new DNS Zone that you will create your records in for this tutorial process. For the examples in this tutorial, we will be using `example.com` as our Zone.
    12  
    13  ## Setting Up UltraDNS Credentials
    14  
    15  The following environment variables will be needed to run ExternalDNS with UltraDNS.
    16  
    17  `ULTRADNS_USERNAME`,`ULTRADNS_PASSWORD`, &`ULTRADNS_BASEURL`
    18  `ULTRADNS_ACCOUNTNAME`(optional variable).
    19  
    20  ## Deploying ExternalDNS
    21  
    22  Connect your `kubectl` client to the cluster you want to test ExternalDNS with.
    23  Then, apply one of the following manifests file to deploy ExternalDNS.
    24  
    25  - Note: We are assuming the zone is already present within UltraDNS.
    26  - Note: While creating CNAMES as target endpoints, the `--txt-prefix` option is mandatory.
    27  ### Manifest (for clusters without RBAC enabled)
    28  
    29  ```yaml
    30  apiVersion: apps/v1
    31  kind: Deployment
    32  metadata:
    33    name: external-dns
    34  spec:
    35    strategy:
    36      type: Recreate
    37    selector:
    38      matchLabels:
    39        app: external-dns
    40    template:
    41      metadata:
    42        labels:
    43          app: external-dns
    44      spec:
    45        containers:
    46        - name: external-dns
    47          image: registry.k8s.io/external-dns/external-dns:v0.14.0
    48          args:
    49          - --source=service 
    50          - --source=ingress # ingress is also possible
    51          - --domain-filter=example.com # (Recommended) We recommend to use this filter as it minimize the time to propagate changes, as there are less number of zones to look into..
    52          - --provider=ultradns
    53          - --txt-prefix=txt-
    54          env:
    55          - name: ULTRADNS_USERNAME
    56            value: ""
    57          - name: ULTRADNS_PASSWORD  # The password is required to be BASE64 encrypted.
    58            value: ""
    59          - name: ULTRADNS_BASEURL
    60            value: "https://api.ultradns.com/"
    61          - name: ULTRADNS_ACCOUNTNAME
    62            value: ""
    63  ```
    64  
    65  ### Manifest (for clusters with RBAC enabled)
    66  
    67  ```yaml
    68  apiVersion: v1
    69  kind: ServiceAccount
    70  metadata:
    71    name: external-dns
    72  ---
    73  apiVersion: rbac.authorization.k8s.io/v1
    74  kind: ClusterRole
    75  metadata:
    76    name: external-dns
    77  rules:
    78  - apiGroups: [""]
    79    resources: ["services","endpoints","pods"]
    80    verbs: ["get","watch","list"]
    81  - apiGroups: ["extensions"]
    82    resources: ["ingresses"]
    83    verbs: ["get","watch","list"]
    84  - apiGroups: [""]
    85    resources: ["nodes"]
    86    verbs: ["list","watch"]
    87  ---
    88  apiVersion: rbac.authorization.k8s.io/v1
    89  kind: ClusterRoleBinding
    90  metadata:
    91    name: external-dns-viewer
    92  roleRef:
    93    apiGroup: rbac.authorization.k8s.io
    94    kind: ClusterRole
    95    name: external-dns
    96  subjects:
    97  - kind: ServiceAccount
    98    name: external-dns
    99    namespace: default
   100  ---
   101  apiVersion: apps/v1
   102  kind: Deployment
   103  metadata:
   104    name: external-dns
   105  spec:
   106    strategy:
   107      type: Recreate
   108    selector:
   109      matchLabels:
   110        app: external-dns
   111    template:
   112      metadata:
   113        labels:
   114          app: external-dns
   115      spec:
   116        serviceAccountName: external-dns
   117        containers:
   118        - name: external-dns
   119          image: registry.k8s.io/external-dns/external-dns:v0.14.0
   120          args:
   121          - --source=service 
   122          - --source=ingress
   123          - --domain-filter=example.com #(Recommended) We recommend to use this filter as it minimize the time to propagate changes, as there are less number of zones to look into..
   124          - --provider=ultradns
   125          - --txt-prefix=txt-
   126          env:
   127          - name: ULTRADNS_USERNAME
   128            value: ""
   129          - name: ULTRADNS_PASSWORD # The password is required to be BASE64 encrypted.
   130            value: ""
   131          - name: ULTRADNS_BASEURL
   132            value: "https://api.ultradns.com/"
   133          - name: ULTRADNS_ACCOUNTNAME
   134            value: ""
   135  ```
   136  
   137  ## Deploying an Nginx Service
   138  
   139  Create a service file called 'nginx.yaml' with the following contents:
   140  
   141  ```yaml
   142  apiVersion: apps/v1
   143  kind: Deployment
   144  metadata:
   145    name: nginx
   146  spec:
   147    selector:
   148      matchLabels:
   149        app: nginx
   150    template:
   151      metadata:
   152        labels:
   153          app: nginx
   154      spec:
   155        containers:
   156        - image: nginx
   157          name: nginx
   158          ports:
   159          - containerPort: 80
   160  ---
   161  apiVersion: v1
   162  kind: Service
   163  metadata:
   164    name: nginx
   165    annotations:
   166      external-dns.alpha.kubernetes.io/hostname: my-app.example.com.
   167  spec:
   168    selector:
   169      app: nginx
   170    type: LoadBalancer
   171    ports:
   172      - protocol: TCP
   173        port: 80
   174        targetPort: 80
   175  ```
   176  
   177  Please note the annotation on the service. Use the same hostname as the UltraDNS zone created above.
   178  
   179  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.
   180  
   181  ## Creating the Deployment and Service:
   182  
   183  ```console
   184  $ kubectl create -f nginx.yaml
   185  $ kubectl create -f external-dns.yaml
   186  ```
   187  
   188  Depending on where you run your service from, it can take a few minutes for your cloud provider to create an external IP for the service.
   189  
   190  Once the service has an external IP assigned, ExternalDNS will notice the new service IP address and will synchronize the UltraDNS records.
   191  
   192  ## Verifying UltraDNS Records
   193  
   194  Please verify on the [UltraDNS UI](https://portal.ultradns.com/login) that the records are created under the zone "example.com".
   195  
   196  For more information on UltraDNS UI, refer to (https://docs.ultradns.com/Content/MSP_User_Guide/Content/User%20Guides/MSP_User_Guide/Navigation/Moving%20Around%20the%20UI.htm#_Toc2780722).
   197  
   198  Select the zone that was created above (or select the appropriate zone if a different zone was used.)
   199  
   200  The external IP address will be displayed as a CNAME record for your zone.
   201  
   202  ## Cleaning Up the Deployment and Service
   203  
   204  Now that we have verified that ExternalDNS will automatically manage your UltraDNS records, you can delete example zones that you created in this tutorial:
   205  
   206  ```
   207  $ kubectl delete service -f nginx.yaml
   208  $ kubectl delete service -f externaldns.yaml
   209  ```
   210  ## Examples to Manage your Records
   211  ### Creating Multiple A Records Target
   212  - First, you want to create a service file called 'apple-banana-echo.yaml' 
   213  ```yaml
   214  ---
   215  kind: Pod
   216  apiVersion: v1
   217  metadata:
   218    name: example-app
   219    labels:
   220      app: apple
   221  spec:
   222    containers:
   223      - name: example-app
   224        image: hashicorp/http-echo
   225        args:
   226          - "-text=apple"
   227  ---
   228  kind: Service
   229  apiVersion: v1
   230  metadata:
   231    name: example-service
   232  spec:
   233    selector:
   234      app: apple
   235    ports:
   236      - port: 5678 # Default port for image
   237  ```
   238  - Then, create service file called 'expose-apple-banana-app.yaml' to expose the services. For more information to deploy ingress controller, refer to (https://kubernetes.github.io/ingress-nginx/deploy/)
   239  ```yaml
   240  apiVersion: networking.k8s.io/v1
   241  kind: Ingress
   242  metadata:
   243    name: example-ingress
   244    annotations:
   245      ingress.kubernetes.io/rewrite-target: /
   246      ingress.kubernetes.io/scheme: internet-facing
   247      external-dns.alpha.kubernetes.io/hostname: apple.example.com.
   248      external-dns.alpha.kubernetes.io/target: 10.10.10.1,10.10.10.23
   249  spec:
   250    rules:
   251    - http:
   252        paths:
   253          - path: /apple
   254            pathType: Prefix
   255            backend:
   256              service:
   257                name: example-service
   258                port:
   259                  number: 5678
   260  ```
   261  - Then, create the deployment and service:
   262  ```console
   263  $ kubectl create -f apple-banana-echo.yaml
   264  $ kubectl create -f expose-apple-banana-app.yaml
   265  $ kubectl create -f external-dns.yaml
   266  ```
   267  - Depending on where you run your service from, it can take a few minutes for your cloud provider to create an external IP for the service.
   268  - Please verify on the [UltraDNS UI](https://portal.ultradns.com/login) that the records have been created under the zone "example.com".
   269  - Finally, you will need to clean up the deployment and service. Please verify on the UI afterwards that the records have been deleted from the zone "example.com":
   270  ```console
   271  $ kubectl delete -f apple-banana-echo.yaml
   272  $ kubectl delete -f expose-apple-banana-app.yaml
   273  $ kubectl delete -f external-dns.yaml
   274  ```
   275  ### Creating CNAME Record
   276  - Please note, that prior to deploying the external-dns service, you will need to add the option –txt-prefix=txt- into external-dns.yaml. If this not provided, your records will not be created.
   277  -  First, create a service file called 'apple-banana-echo.yaml'
   278      - _Config File Example – kubernetes cluster is on-premise not on cloud_
   279      ```yaml
   280      ---
   281      kind: Pod
   282      apiVersion: v1
   283      metadata:
   284        name: example-app
   285        labels:
   286          app: apple
   287      spec:
   288        containers:
   289          - name: example-app
   290            image: hashicorp/http-echo
   291            args:
   292              - "-text=apple"
   293      ---
   294      kind: Service
   295      apiVersion: v1
   296      metadata:
   297        name: example-service
   298      spec:
   299        selector:
   300          app: apple
   301        ports:
   302          - port: 5678 # Default port for image
   303      ---
   304      apiVersion: networking.k8s.io/v1
   305      kind: Ingress
   306      metadata:
   307        name: example-ingress
   308        annotations:
   309          ingress.kubernetes.io/rewrite-target: /
   310          ingress.kubernetes.io/scheme: internet-facing
   311          external-dns.alpha.kubernetes.io/hostname: apple.example.com.
   312          external-dns.alpha.kubernetes.io/target: apple.cname.com.
   313      spec:
   314        rules:
   315        - http:
   316            paths:
   317              - path: /apple
   318                backend:
   319                  service:
   320                    name: example-service
   321                    port:
   322                      number: 5678
   323      ```
   324      - _Config File Example – Kubernetes cluster service from different cloud vendors_
   325      ```yaml
   326      ---
   327      kind: Pod
   328      apiVersion: v1
   329      metadata:
   330        name: example-app
   331        labels:
   332          app: apple
   333      spec:
   334        containers:
   335          - name: example-app
   336            image: hashicorp/http-echo
   337            args:
   338              - "-text=apple"
   339      ---
   340      kind: Service
   341      apiVersion: v1
   342      metadata:
   343        name: example-service
   344        annotations:
   345          external-dns.alpha.kubernetes.io/hostname: my-app.example.com.
   346      spec:
   347        selector:
   348          app: apple
   349        type: LoadBalancer
   350        ports:
   351          - protocol: TCP
   352            port: 5678
   353            targetPort: 5678
   354      ```
   355  - Then, create the deployment and service:
   356  ```console
   357  $ kubectl create -f apple-banana-echo.yaml
   358  $ kubectl create -f external-dns.yaml
   359  ```
   360  - Depending on where you run your service from, it can take a few minutes for your cloud provider to create an external IP for the service.
   361  - Please verify on the [UltraDNS UI](https://portal.ultradns.com/login), that the records have been created under the zone "example.com".
   362  - Finally, you will need to clean up the deployment and service. Please verify on the UI afterwards that the records have been deleted from the zone "example.com":
   363  ```console
   364  $ kubectl delete -f apple-banana-echo.yaml
   365  $ kubectl delete -f external-dns.yaml
   366  ```
   367  ### Creating Multiple Types Of Records
   368  - Please note, that prior to deploying the external-dns service, you will need to add the option –txt-prefix=txt- into external-dns.yaml. Since you will also be created a CNAME record, If this not provided, your records will not be created.
   369  -  First, create a service file called 'apple-banana-echo.yaml'
   370      - _Config File Example – kubernetes cluster is on-premise not on cloud_
   371      ```yaml
   372      ---
   373      kind: Pod
   374      apiVersion: v1
   375      metadata:
   376        name: example-app
   377        labels:
   378          app: apple
   379      spec:
   380        containers:
   381          - name: example-app
   382            image: hashicorp/http-echo
   383            args:
   384              - "-text=apple"
   385      ---
   386      kind: Service
   387      apiVersion: v1
   388      metadata:
   389        name: example-service
   390      spec:
   391        selector:
   392          app: apple
   393        ports:
   394          - port: 5678 # Default port for image
   395      ---
   396      kind: Pod
   397      apiVersion: v1
   398      metadata:
   399        name: example-app1
   400        labels:
   401          app: apple1
   402      spec:
   403        containers:
   404          - name: example-app1
   405            image: hashicorp/http-echo
   406            args:
   407              - "-text=apple"
   408      ---
   409      kind: Service
   410      apiVersion: v1
   411      metadata:
   412        name: example-service1
   413      spec:
   414        selector:
   415          app: apple1
   416        ports:
   417          - port: 5679 # Default port for image
   418      ---
   419      kind: Pod
   420      apiVersion: v1
   421      metadata:
   422        name: example-app2
   423        labels:
   424          app: apple2
   425      spec:
   426        containers:
   427          - name: example-app2
   428            image: hashicorp/http-echo
   429            args:
   430              - "-text=apple"
   431      ---
   432      kind: Service
   433      apiVersion: v1
   434      metadata:
   435        name: example-service2
   436      spec:
   437        selector:
   438          app: apple2
   439        ports:
   440          - port: 5680 # Default port for image
   441      ---
   442      apiVersion: networking.k8s.io/v1
   443      kind: Ingress
   444      metadata:
   445        name: example-ingress
   446        annotations:
   447          ingress.kubernetes.io/rewrite-target: /
   448          ingress.kubernetes.io/scheme: internet-facing
   449          external-dns.alpha.kubernetes.io/hostname: apple.example.com.
   450          external-dns.alpha.kubernetes.io/target: apple.cname.com.
   451      spec:
   452        rules:
   453        - http:
   454            paths:
   455              - path: /apple
   456                backend:
   457                  service:
   458                    name: example-service
   459                    port:
   460                      number: 5678
   461      ---
   462      apiVersion: networking.k8s.io/v1
   463      kind: Ingress
   464      metadata:
   465        name: example-ingress1
   466        annotations:
   467          ingress.kubernetes.io/rewrite-target: /
   468          ingress.kubernetes.io/scheme: internet-facing
   469          external-dns.alpha.kubernetes.io/hostname: apple-banana.example.com.
   470          external-dns.alpha.kubernetes.io/target: 10.10.10.3
   471      spec:
   472        rules:
   473        - http:
   474            paths:
   475              - path: /apple
   476                backend:
   477                  service:
   478                    name: example-service1
   479                    port:
   480                      number: 5679
   481      ---
   482      apiVersion: networking.k8s.io/v1
   483      kind: Ingress
   484      metadata:
   485        name: example-ingress2
   486        annotations:
   487          ingress.kubernetes.io/rewrite-target: /
   488          ingress.kubernetes.io/scheme: internet-facing
   489          external-dns.alpha.kubernetes.io/hostname: banana.example.com.
   490          external-dns.alpha.kubernetes.io/target: 10.10.10.3,10.10.10.20
   491      spec:
   492        rules:
   493        - http:
   494            paths:
   495              - path: /apple
   496                backend:
   497                  service:
   498                    name: example-service2
   499                    port:
   500                      number: 5680
   501      ```
   502      - _Config File Example – Kubernetes cluster service from different cloud vendors_
   503      ```yaml
   504      ---
   505      apiVersion: apps/v1
   506      kind: Deployment
   507      metadata:
   508        name: nginx
   509      spec:
   510        selector:
   511          matchLabels:
   512            app: nginx
   513        template:
   514          metadata:
   515            labels:
   516              app: nginx
   517          spec:
   518            containers:
   519            - image: nginx
   520              name: nginx
   521              ports:
   522              - containerPort: 80
   523      ---
   524      apiVersion: v1
   525      kind: Service
   526      metadata:
   527        name: nginx
   528        annotations:
   529          external-dns.alpha.kubernetes.io/hostname: my-app.example.com.
   530      spec:
   531        selector:
   532          app: nginx
   533        type: LoadBalancer
   534        ports:
   535          - protocol: TCP
   536            port: 80
   537            targetPort: 80
   538      ---
   539      kind: Pod
   540      apiVersion: v1
   541      metadata:
   542        name: example-app
   543        labels:
   544          app: apple
   545      spec:
   546        containers:
   547          - name: example-app
   548            image: hashicorp/http-echo
   549            args:
   550              - "-text=apple"
   551      ---
   552      kind: Service
   553      apiVersion: v1
   554      metadata:
   555        name: example-service
   556      spec:
   557        selector:
   558          app: apple
   559        ports:
   560          - port: 5678 # Default port for image
   561      ---
   562      kind: Pod
   563      apiVersion: v1
   564      metadata:
   565        name: example-app1
   566        labels:
   567          app: apple1
   568      spec:
   569        containers:
   570          - name: example-app1
   571            image: hashicorp/http-echo
   572            args:
   573              - "-text=apple"
   574      ---
   575      apiVersion: extensions/v1beta1
   576      kind: Service
   577      apiVersion: v1
   578      metadata:
   579        name: example-service1
   580      spec:
   581        selector:
   582          app: apple1
   583        ports:
   584          - port: 5679 # Default port for image
   585      ---
   586      apiVersion: networking.k8s.io/v1
   587      kind: Ingress
   588      metadata:
   589        name: example-ingress
   590        annotations:
   591          ingress.kubernetes.io/rewrite-target: /
   592          ingress.kubernetes.io/scheme: internet-facing
   593          external-dns.alpha.kubernetes.io/hostname: apple.example.com.
   594          external-dns.alpha.kubernetes.io/target: 10.10.10.3,10.10.10.25
   595      spec:
   596        rules:
   597        - http:
   598            paths:
   599              - path: /apple
   600                backend:
   601                  service:
   602                    name: example-service
   603                    port:
   604                      number: 5678
   605      ---
   606      apiVersion: networking.k8s.io/v1
   607      kind: Ingress
   608      metadata:
   609        name: example-ingress1
   610        annotations:
   611          ingress.kubernetes.io/rewrite-target: /
   612          ingress.kubernetes.io/scheme: internet-facing
   613          external-dns.alpha.kubernetes.io/hostname: apple-banana.example.com.
   614          external-dns.alpha.kubernetes.io/target: 10.10.10.3
   615      spec:
   616        rules:
   617        - http:
   618            paths:
   619              - path: /apple
   620                backend:
   621                  service:
   622                    name: example-service1
   623                    port:
   624                      number: 5679
   625      ```
   626  - Then, create the deployment and service:
   627  ```console
   628  $ kubectl create -f apple-banana-echo.yaml
   629  $ kubectl create -f external-dns.yaml
   630  ```
   631  - Depending on where you run your service from, it can take a few minutes for your cloud provider to create an external IP for the service.
   632  - Please verify on the [UltraDNS UI](https://portal.ultradns.com/login), that the records have been created under the zone "example.com".
   633  - Finally, you will need to clean up the deployment and service. Please verify on the UI afterwards that the records have been deleted from the zone "example.com":
   634  ```console 
   635  $ kubectl delete -f apple-banana-echo.yaml
   636  $ kubectl delete -f external-dns.yaml```