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

     1  # Setting up ExternalDNS for Services on IBMCloud
     2  
     3  This tutorial describes how to setup ExternalDNS for usage within a Kubernetes cluster using IBMCloud DNS.
     4  
     5  This tutorial uses [IBMCloud CLI](https://cloud.ibm.com/docs/cli?topic=cli-getting-started) for all
     6  IBM Cloud commands and assumes that the Kubernetes cluster was created via IBM Cloud Kubernetes Service and `kubectl` commands
     7  are being run on an orchestration node.
     8  
     9  ## Creating a IBMCloud DNS zone
    10  The IBMCloud provider for ExternalDNS will find suitable zones for domains it manages; it will
    11  not automatically create zones.
    12  For public zone, This tutorial assume that the [IBMCloud Internet Services](https://cloud.ibm.com/catalog/services/internet-services) was provisioned and the [cis cli plugin](https://cloud.ibm.com/docs/cis?topic=cis-cli-plugin-cis-cli) was installed with IBMCloud CLI
    13  For private zone, This tutorial assume that the [IBMCloud DNS Services](https://cloud.ibm.com/catalog/services/dns-services) was provisioned and the [dns cli plugin](https://cloud.ibm.com/docs/dns-svcs?topic=dns-svcs-cli-plugin-dns-services-cli-commands) was installed with IBMCloud CLI
    14  
    15  ### Public Zone
    16  For this tutorial, we create public zone named `example.com` on IBMCloud Internet Services instance `external-dns-public`
    17  ```
    18  $ ibmcloud cis domain-add example.com -i external-dns-public
    19  ```
    20  Follow [step](https://cloud.ibm.com/docs/cis?topic=cis-getting-started#configure-your-name-servers-with-the-registrar-or-existing-dns-provider) to active your zone
    21  
    22  ### Private Zone
    23  For this tutorial, we create private zone named `example.com` on IBMCloud DNS Services instance `external-dns-private`
    24  ```
    25  $ ibmcloud dns zone-create example.com -i external-dns-private
    26  ```
    27  
    28  ## Creating configuration file
    29  
    30  The preferred way to inject the configuration file is by using a Kubernetes secret. The secret should contain an object named azure.json with content similar to this:
    31  
    32  ```
    33  {
    34    "apiKey": "1234567890abcdefghijklmnopqrstuvwxyz",
    35    "instanceCrn": "crn:v1:bluemix:public:internet-svcs:global:a/bcf1865e99742d38d2d5fc3fb80a5496:b950da8a-5be6-4691-810e-36388c77b0a3::"
    36  }
    37  ```
    38  
    39  You can create or find the `apiKey` in your ibmcloud IAM --> [API Keys page](https://cloud.ibm.com/iam/apikeys)
    40  
    41  You can find the `instanceCrn` in your service instance details
    42  
    43  Now you can create a file named 'ibmcloud.json' with values gathered above and with the structure of the example above. Use this file to create a Kubernetes secret:
    44  ```
    45  $ kubectl create secret generic ibmcloud-config-file --from-file=/local/path/to/ibmcloud.json
    46  ```
    47  ## Deploy ExternalDNS
    48  
    49  Connect your `kubectl` client to the cluster you want to test ExternalDNS with.
    50  Then apply one of the following manifests file to deploy ExternalDNS.
    51  
    52  ### Manifest (for clusters without RBAC enabled)
    53  
    54  ```yaml
    55  apiVersion: apps/v1
    56  kind: Deployment
    57  metadata:
    58    name: external-dns
    59  spec:
    60    strategy:
    61      type: Recreate
    62    selector:
    63      matchLabels:
    64        app: external-dns
    65    template:
    66      metadata:
    67        labels:
    68          app: external-dns
    69      spec:
    70        containers:
    71        - name: external-dns
    72          image: registry.k8s.io/external-dns/external-dns:v0.14.0
    73          args:
    74          - --source=service # ingress is also possible
    75          - --domain-filter=example.com # (optional) limit to only example.com domains; change to match the zone created above.
    76          - --provider=ibmcloud
    77          - --ibmcloud-proxied # (optional) enable the proxy feature of IBMCloud
    78          volumeMounts:
    79          - name: ibmcloud-config-file
    80            mountPath: /etc/kubernetes
    81            readOnly: true
    82        volumes:
    83        - name: ibmcloud-config-file
    84          secret:
    85            secretName: ibmcloud-config-file
    86            items:
    87            - key: externaldns-config.json
    88              path: ibmcloud.json
    89  ```
    90  
    91  ### Manifest (for clusters with RBAC enabled)
    92  
    93  ```yaml
    94  apiVersion: v1
    95  kind: ServiceAccount
    96  metadata:
    97    name: external-dns
    98  ---
    99  apiVersion: rbac.authorization.k8s.io/v1
   100  kind: ClusterRole
   101  metadata:
   102    name: external-dns
   103  rules:
   104  - apiGroups: [""]
   105    resources: ["services","endpoints","pods"]
   106    verbs: ["get","watch","list"]
   107  - apiGroups: ["extensions","networking.k8s.io"]
   108    resources: ["ingresses"] 
   109    verbs: ["get","watch","list"]
   110  - apiGroups: [""]
   111    resources: ["nodes"]
   112    verbs: ["list", "watch"]
   113  ---
   114  apiVersion: rbac.authorization.k8s.io/v1
   115  kind: ClusterRoleBinding
   116  metadata:
   117    name: external-dns-viewer
   118  roleRef:
   119    apiGroup: rbac.authorization.k8s.io
   120    kind: ClusterRole
   121    name: external-dns
   122  subjects:
   123  - kind: ServiceAccount
   124    name: external-dns
   125    namespace: default
   126  ---
   127  apiVersion: apps/v1
   128  kind: Deployment
   129  metadata:
   130    name: external-dns
   131  spec:
   132    strategy:
   133      type: Recreate
   134    selector:
   135      matchLabels:
   136        app: external-dns
   137    template:
   138      metadata:
   139        labels:
   140          app: external-dns
   141      spec:
   142        serviceAccountName: external-dns
   143        containers:
   144        - name: external-dns
   145          image: registry.k8s.io/external-dns/external-dns:v0.14.0
   146          args:
   147          - --source=service # ingress is also possible
   148          - --domain-filter=example.com # (optional) limit to only example.com domains; change to match the zone created above.
   149          - --provider=ibmcloud
   150          - --ibmcloud-proxied # (optional) enable the proxy feature of IBMCloud public zone
   151          volumeMounts:
   152          - name: ibmcloud-config-file
   153            mountPath: /etc/kubernetes
   154            readOnly: true
   155        volumes:
   156        - name: ibmcloud-config-file
   157          secret:
   158            secretName: ibmcloud-config-file
   159            items:
   160            - key: externaldns-config.json
   161              path: ibmcloud.json
   162  ```
   163  
   164  ## Deploying an Nginx Service
   165  
   166  Create a service file called `nginx.yaml` with the following contents:
   167  
   168  ```yaml
   169  apiVersion: apps/v1
   170  kind: Deployment
   171  metadata:
   172    name: nginx
   173  spec:
   174    selector:
   175      matchLabels:
   176        app: nginx
   177    template:
   178      metadata:
   179        labels:
   180          app: nginx
   181      spec:
   182        containers:
   183        - image: nginx
   184          name: nginx
   185          ports:
   186          - containerPort: 80
   187  ---
   188  apiVersion: v1
   189  kind: Service
   190  metadata:
   191    name: nginx
   192    annotations:
   193      external-dns.alpha.kubernetes.io/hostname: www.example.com
   194      external-dns.alpha.kubernetes.io/ttl: "120" #optional
   195  spec:
   196    selector:
   197      app: nginx
   198    type: LoadBalancer
   199    ports:
   200      - protocol: TCP
   201        port: 80
   202        targetPort: 80
   203  ```
   204  
   205  Note the annotation on the service; use the hostname as the IBMCloud DNS zone created above. The annotation may also be a subdomain
   206  of the DNS zone (e.g. 'www.example.com').
   207  
   208  By setting the TTL annotation on the service, you have to pass a valid TTL, which must be 120 or above.
   209  This annotation is optional, if you won't set it, it will be 1 (automatic) which is 300.
   210  
   211  ExternalDNS uses this annotation to determine what services should be registered with DNS.  Removing the annotation
   212  will cause ExternalDNS to remove the corresponding DNS records.
   213  
   214  Create the deployment and service:
   215  
   216  ```
   217  $ kubectl create -f nginx.yaml
   218  ```
   219  
   220  Depending where you run your service it can take a little while for your cloud provider to create an external IP for the service.
   221  
   222  Once the service has an external IP assigned, ExternalDNS will notice the new service IP address and synchronize
   223  the IBMCloud DNS records.
   224  
   225  ## Verifying IBMCloud DNS records
   226  Run the following command to view the A records:
   227  
   228  ### Public Zone
   229  ```
   230  # Get the domain ID with below command on IBMCloud Internet Services instance `external-dns-public`
   231  $ ibmcloud cis domains -i external-dns-public
   232  # Get the records with domain ID
   233  $ ibmcloud cis dns-records DOMAIN_ID  -i external-dns-public
   234  ```
   235  
   236  ### Private Zone
   237  ```
   238  # Get the domain ID with below command on IBMCloud DNS Services instance `external-dns-private`
   239  $ ibmcloud dns zones -i external-dns-private
   240  # Get the records with domain ID
   241  $ ibmcloud dns resource-records ZONE_ID  -i external-dns-public
   242  ```
   243  This should show the external IP address of the service as the A record for your domain.
   244  
   245  ## Cleanup
   246  
   247  Now that we have verified that ExternalDNS will automatically manage IBMCloud DNS records, we can delete the tutorial's example:
   248  
   249  ```
   250  $ kubectl delete -f nginx.yaml
   251  $ kubectl delete -f externaldns.yaml
   252  ```
   253  
   254  ## Setting proxied records on public zone
   255  
   256  Using the `external-dns.alpha.kubernetes.io/ibmcloud-proxied: "true"` annotation on your ingress or service, you can specify if the proxy feature of IBMCloud public DNS should be enabled for that record. This setting will override the global `--ibmcloud-proxied` setting.
   257  
   258  ## Active priviate zone with VPC allocated
   259  
   260  By default, IBMCloud DNS Services don't active your private zone with new zone added, with externale DNS, you can use `external-dns.alpha.kubernetes.io/ibmcloud-vpc: "crn:v1:bluemix:public:is:us-south:a/bcf1865e99742d38d2d5fc3fb80a5496::vpc:r006-74353823-a60d-42e4-97c5-5e2551278435"` annotation on your ingress or service, it will active your private zone with in specific VPC for that record created in. this setting won't work if the private zone was active already.
   261  
   262  Note: the annotaion value is the VPC CRN, every IBM Cloud service have a valid CRN.