ExternalDNS Operator

The ExternalDNS Operator allows you to deploy and manage ExternalDNS, a cluster-internal component which makes Kubernetes resources discoverable through public DNS servers. For more information about the initial motivation, see ExternalDNS Operator OpenShift Enhancement Proposal.

• Deploying the ExternalDNS Operator
  • Preparing the environment
  • Installing the ExternalDNS Operator by building and pushing the Operator image to a registry
  • Installing the ExternalDNS Operator using a custom index image on OperatorHub
• Running end-to-end tests manually
• Proxy support

Deploying the ExternalDNS Operator

The following procedure describes how to deploy the ExternalDNS Operator for AWS.

Preparing the environment

Prepare your environment for the installation commands.

• Select the container runtime you want to build the images with (podman or docker):

  export CONTAINER_ENGINE=podman

• Select the name settings of the image:

  export REGISTRY=quay.io
  export REPOSITORY=myuser
  export VERSION=1.0.0

• Login to the image registry:

  ${CONTAINER_ENGINE} login ${REGISTRY} -u ${REPOSITORY}

Installing the ExternalDNS Operator by building and pushing the Operator image to a registry

1. Build and push the Operator image to a registry:

   export IMG=${REGISTRY}/${REPOSITORY}/external-dns-operator:${VERSION}
   make image-build image-push

2. Prepare the operand namespace:

   kubectl create ns external-dns
   kubectl apply -f config/rbac/extra-roles.yaml

3. Run the following command to deploy the ExternalDNS Operator:

   make deploy

4. The previous step deploys the validation webhook, which requires TLS authentication for the webhook server. The manifests deployed through the make deploy command do not contain a valid certificate and key. You must provision a valid certificate and key through other tools. You can use a convenience script, hack/generate-certs.sh to generate the certificate bundle and patch the validation webhook config.
   Important: Do not use the hack/generate-certs.sh script in a production environment.
   Run the hack/generate-certs.sh script with the following inputs:

   hack/generate-certs.sh --service webhook-service --webhook validating-webhook-configuration \
   --secret webhook-server-cert --namespace external-dns-operator

5. Now you can deploy an instance of ExternalDNS:

   • Run the following command to create the credentials secret for AWS:

     kubectl -n external-dns-operator create secret generic aws-access-key \
             --from-literal=aws_access_key_id=${ACCESS_KEY_ID} \
             --from-literal=aws_secret_access_key=${ACCESS_SECRET_KEY}

     Note: See this guide for instructions specific to other providers.

   • Run the following command:

     # for AWS
     kubectl apply -k config/samples/aws

     Note: For other providers, see config/samples/.

Installing the ExternalDNS Operator using a custom index image on OperatorHub

Note: The below procedure works best with podman as container engine

1. Build and push the operator image to the registry:

   export IMG=${REGISTRY}/${REPOSITORY}/external-dns-operator:${VERSION}
   make image-build image-push

2. Build and push the bundle image to the registry:

   a. In the bundle/manifests/external-dns-operator_clusterserviceversion.yaml add the operator image created in Step 1 as follows:

   sed -i "s|quay.io/openshift/origin-external-dns-operator:latest|${IMG}|g" bundle/manifests/external-dns-operator_clusterserviceversion.yaml

   b. Build the image

   export BUNDLE_IMG=${REGISTRY}/${REPOSITORY}/external-dns-operator-bundle:${VERSION}
   make bundle-image-build bundle-image-push

3. Build and push the index image to the registry:

   export INDEX_IMG=${REGISTRY}/${REPOSITORY}/external-dns-operator-bundle-index:${VERSION}
   make index-image-build index-image-push

4. Prepare the operand namespace:

   oc create ns external-dns
   oc apply -f config/rbac/extra-roles.yaml

5. You may need to link the registry secret to the pod of external-dns-operator created in the openshift-marketplace namespace if the image is not made public (Doc link). If you are using podman then these are the instructions:

   a. Create a secret with authentication details of your image registry:

   oc -n openshift-marketplace create secret generic extdns-olm-secret  --type=kubernetes.io/dockercfg  --from-file=.dockercfg=${XDG_RUNTIME_DIR}/containers/auth.json

   b. Link the secret to default service account:

   oc -n openshift-marketplace secrets link default extdns-olm-secret --for=pull

6. Create the CatalogSource object:

   cat <<EOF | oc apply -f -
   apiVersion: operators.coreos.com/v1alpha1
   kind: CatalogSource
   metadata:
     name: external-dns-operator
     namespace: openshift-marketplace
   spec:
     sourceType: grpc
     image: ${INDEX_IMG}
   EOF

7. Create the operator namespace:

   oc create namespace external-dns-operator

8. Create the OperatorGroup object to scope the operator to external-dns-operator namespace:

   cat <<EOF | oc apply -f -
   apiVersion: operators.coreos.com/v1
   kind: OperatorGroup
   metadata:
     name: external-dns-operator
     namespace: external-dns-operator
   spec:
     targetNamespaces:
     - external-dns-operator
   EOF

9. Create the Subscription object:

   cat <<EOF | oc apply -f -
   apiVersion: operators.coreos.com/v1alpha1
   kind: Subscription
   metadata:
     name: external-dns-operator
     namespace: external-dns-operator
   spec:
     channel: alpha
     name: external-dns-operator
     source: external-dns-operator
     sourceNamespace: openshift-marketplace
   EOF

Note: The steps starting from the 7th can be replaced with the following actions in the web console: Navigate to Operators -> OperatorHub, search for the ExternalDNS Operator, and install it in the external-dns-operator namespace.

Running end-to-end tests manually

1. Deploy the operator as described above

2. Set the necessary environment variables

   For AWS:

   export KUBECONFIG=/path/to/mycluster/kubeconfig
   export CLOUD_PROVIDER=AWS
   export AWS_ACCESS_KEY_ID=my-aws-access-key
   export AWS_SECRET_ACCESS_KEY=my-aws-access-secret

   For the other providers: check out e2e directory.

3. Run the test suite

   make test-e2e

Proxy support

Configuring proxy support for ExternalDNS Operator