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

     1  # Setting up ExternalDNS for Services on Cloudflare
     2  
     3  This tutorial describes how to setup ExternalDNS for usage within a Kubernetes cluster using Cloudflare DNS.
     4  
     5  Make sure to use **>=0.4.2** version of ExternalDNS for this tutorial.
     6  
     7  ## Creating a Cloudflare DNS zone
     8  
     9  We highly recommend to read this tutorial if you haven't used Cloudflare before:
    10  
    11  [Create a Cloudflare account and add a website](https://support.cloudflare.com/hc/en-us/articles/201720164-Step-2-Create-a-Cloudflare-account-and-add-a-website)
    12  
    13  ## Creating Cloudflare Credentials
    14  
    15  Snippet from [Cloudflare - Getting Started](https://api.cloudflare.com/#getting-started-endpoints):
    16  
    17  >Cloudflare's API exposes the entire Cloudflare infrastructure via a standardized programmatic interface. Using Cloudflare's API, you can do just about anything you can do on cloudflare.com via the customer dashboard.
    18  
    19  >The Cloudflare API is a RESTful API based on HTTPS requests and JSON responses. If you are registered with Cloudflare, you can obtain your API key from the bottom of the "My Account" page, found here: [Go to My account](https://dash.cloudflare.com/profile).
    20  
    21  API Token will be preferred for authentication if `CF_API_TOKEN` environment variable is set.
    22  Otherwise `CF_API_KEY` and `CF_API_EMAIL` should be set to run ExternalDNS with Cloudflare.
    23  You may provide the Cloudflare API token through a file by setting the
    24  `CF_API_TOKEN="file:/path/to/token"`.
    25  
    26  When using API Token authentication, the token should be granted Zone `Read`, DNS `Edit` privileges, and access to `All zones`.
    27  
    28  If you would like to further restrict the API permissions to a specific zone (or zones), you also need to use the `--zone-id-filter` so that the underlying API requests only access the zones that you explicitly specify, as opposed to accessing all zones.
    29  
    30  ## Throttling
    31  
    32  Cloudflare API has a [global rate limit of 1,200 requests per five minutes](https://developers.cloudflare.com/fundamentals/api/reference/limits/). Running several fast polling ExternalDNS instances in a given account can easily hit that limit. The AWS Provider [docs](./aws.md#throttling) has some recommendations that can be followed here too, but in particular, consider passing `--cloudflare-dns-records-per-page` with a high value (maximum is 5,000).
    33  
    34  ## Deploy ExternalDNS
    35  
    36  Connect your `kubectl` client to the cluster you want to test ExternalDNS with.
    37  Then apply one of the following manifests file to deploy ExternalDNS.
    38  
    39  ### Manifest (for clusters without RBAC enabled)
    40  
    41  ```yaml
    42  apiVersion: apps/v1
    43  kind: Deployment
    44  metadata:
    45    name: external-dns
    46  spec:
    47    strategy:
    48      type: Recreate
    49    selector:
    50      matchLabels:
    51        app: external-dns
    52    template:
    53      metadata:
    54        labels:
    55          app: external-dns
    56      spec:
    57        containers:
    58        - name: external-dns
    59          image: registry.k8s.io/external-dns/external-dns:v0.14.0
    60          args:
    61          - --source=service # ingress is also possible
    62          - --domain-filter=example.com # (optional) limit to only example.com domains; change to match the zone created above.
    63          - --zone-id-filter=023e105f4ecef8ad9ca31a8372d0c353 # (optional) limit to a specific zone.
    64          - --provider=cloudflare
    65          - --cloudflare-proxied # (optional) enable the proxy feature of Cloudflare (DDOS protection, CDN...)
    66          - --cloudflare-dns-records-per-page=5000 # (optional) configure how many DNS records to fetch per request
    67          env:
    68          - name: CF_API_KEY
    69            value: "YOUR_CLOUDFLARE_API_KEY"
    70          - name: CF_API_EMAIL
    71            value: "YOUR_CLOUDFLARE_EMAIL"
    72  ```
    73  
    74  ### Manifest (for clusters with RBAC enabled)
    75  
    76  ```yaml
    77  apiVersion: v1
    78  kind: ServiceAccount
    79  metadata:
    80    name: external-dns
    81  ---
    82  apiVersion: rbac.authorization.k8s.io/v1
    83  kind: ClusterRole
    84  metadata:
    85    name: external-dns
    86  rules:
    87  - apiGroups: [""]
    88    resources: ["services","endpoints","pods"]
    89    verbs: ["get","watch","list"]
    90  - apiGroups: ["extensions","networking.k8s.io"]
    91    resources: ["ingresses"]
    92    verbs: ["get","watch","list"]
    93  - apiGroups: [""]
    94    resources: ["nodes"]
    95    verbs: ["list", "watch"]
    96  ---
    97  apiVersion: rbac.authorization.k8s.io/v1
    98  kind: ClusterRoleBinding
    99  metadata:
   100    name: external-dns-viewer
   101  roleRef:
   102    apiGroup: rbac.authorization.k8s.io
   103    kind: ClusterRole
   104    name: external-dns
   105  subjects:
   106  - kind: ServiceAccount
   107    name: external-dns
   108    namespace: default
   109  ---
   110  apiVersion: apps/v1
   111  kind: Deployment
   112  metadata:
   113    name: external-dns
   114  spec:
   115    strategy:
   116      type: Recreate
   117    selector:
   118      matchLabels:
   119        app: external-dns
   120    template:
   121      metadata:
   122        labels:
   123          app: external-dns
   124      spec:
   125        serviceAccountName: external-dns
   126        containers:
   127        - name: external-dns
   128          image: registry.k8s.io/external-dns/external-dns:v0.14.0
   129          args:
   130          - --source=service # ingress is also possible
   131          - --domain-filter=example.com # (optional) limit to only example.com domains; change to match the zone created above.
   132          - --zone-id-filter=023e105f4ecef8ad9ca31a8372d0c353 # (optional) limit to a specific zone.
   133          - --provider=cloudflare
   134          - --cloudflare-proxied # (optional) enable the proxy feature of Cloudflare (DDOS protection, CDN...)
   135          - --cloudflare-dns-records-per-page=5000 # (optional) configure how many DNS records to fetch per request
   136          env:
   137          - name: CF_API_KEY
   138            value: "YOUR_CLOUDFLARE_API_KEY"
   139          - name: CF_API_EMAIL
   140            value: "YOUR_CLOUDFLARE_EMAIL"
   141  ```
   142  
   143  ## Deploying an Nginx Service
   144  
   145  Create a service file called 'nginx.yaml' with the following contents:
   146  
   147  ```yaml
   148  apiVersion: apps/v1
   149  kind: Deployment
   150  metadata:
   151    name: nginx
   152  spec:
   153    selector:
   154      matchLabels:
   155        app: nginx
   156    template:
   157      metadata:
   158        labels:
   159          app: nginx
   160      spec:
   161        containers:
   162        - image: nginx
   163          name: nginx
   164          ports:
   165          - containerPort: 80
   166  ---
   167  apiVersion: v1
   168  kind: Service
   169  metadata:
   170    name: nginx
   171    annotations:
   172      external-dns.alpha.kubernetes.io/hostname: example.com
   173      external-dns.alpha.kubernetes.io/ttl: "120" #optional
   174  spec:
   175    selector:
   176      app: nginx
   177    type: LoadBalancer
   178    ports:
   179      - protocol: TCP
   180        port: 80
   181        targetPort: 80
   182  ```
   183  
   184  Note the annotation on the service; use the same hostname as the Cloudflare DNS zone created above. The annotation may also be a subdomain
   185  of the DNS zone (e.g. 'www.example.com').
   186  
   187  By setting the TTL annotation on the service, you have to pass a valid TTL, which must be 120 or above.
   188  This annotation is optional, if you won't set it, it will be 1 (automatic) which is 300.
   189  For Cloudflare proxied entries, set the TTL annotation to 1 (automatic), or do not set it.
   190  
   191  ExternalDNS uses this annotation to determine what services should be registered with DNS.  Removing the annotation
   192  will cause ExternalDNS to remove the corresponding DNS records.
   193  
   194  Create the deployment and service:
   195  
   196  ```
   197  $ kubectl create -f nginx.yaml
   198  ```
   199  
   200  Depending where you run your service it can take a little while for your cloud provider to create an external IP for the service.
   201  
   202  Once the service has an external IP assigned, ExternalDNS will notice the new service IP address and synchronize
   203  the Cloudflare DNS records.
   204  
   205  ## Verifying Cloudflare DNS records
   206  
   207  Check your [Cloudflare dashboard](https://www.cloudflare.com/a/dns/example.com) to view the records for your Cloudflare DNS zone.
   208  
   209  Substitute the zone for the one created above if a different domain was used.
   210  
   211  This should show the external IP address of the service as the A record for your domain.
   212  
   213  ## Cleanup
   214  
   215  Now that we have verified that ExternalDNS will automatically manage Cloudflare DNS records, we can delete the tutorial's example:
   216  
   217  ```
   218  $ kubectl delete -f nginx.yaml
   219  $ kubectl delete -f externaldns.yaml
   220  ```
   221  
   222  ## Setting cloudflare-proxied on a per-ingress basis
   223  
   224  Using the `external-dns.alpha.kubernetes.io/cloudflare-proxied: "true"` annotation on your ingress, you can specify if the proxy feature of Cloudflare should be enabled for that record. This setting will override the global `--cloudflare-proxied` setting.