FAQs: Amazon EKS add-ons

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshoot AWS CLI errors. Also, make sure that you're using the most recent AWS CLI version.

Q: How do I check the reason for the failed deployment of an Amazon EKS add-on in my Amazon EKS cluster?

To check the reason for the failure, use the Amazon EKS console or AWS CLI.

On the Amazon EKS console, complete the following steps:

1. Open the Amazon EKS console.
2. In the navigation pane, choose Clusters. Then, select the name of the cluster that you want to create the add-on for.
3. Choose the Add-ons tab.
4. Select the add-on that's in the Degraded, Pending, or Inactive state. You can find the reason for the failure in the Health issues section.

-or-

Run the AWS CLI describe-addon command:

$ aws eks describe-addon --cluster-name example-cluster --addon-name coredns

You can find the reason for the failure in the Addonissue object.

Example output:

{    "addon": {
        "addonName": "coredns",
        "clusterName": "eksn",
        "status": "DEGRADED",
        "addonVersion": "v1.8.7-eksbuild.4",
        "health": {
            "issues": \[
                {
                    "code": "InsufficientNumberOfReplicas",
                    "message": "The add-on is unhealthy because it doesn't have the desired number of replicas."
                }
            \]
        }
        "addonArn": "arn:aws:eks:us-east-2:acc-ID:addon/EKS\_CLUSTER/coredns/76c68b04-0804-2419-8da6-90d8318af308",
        "createdAt": "2024-01-17T06:07:23.826000+00:00",
        "modifiedAt": "2024-04-19T04:40:03.537000+00:00",
        "tags": {}
    }
}

Q: I received the following error message: "The add-on is unhealthy because it doesn't have the desired number of replicas." How do I troubleshoot this error?

To check the corresponding pod's state in the cluster, run the following commands:

kubectl get pods -n kube-system
kubectl describe pod pod-name -n kube-system
kubectl logs pod-name -n kube-system

Replace pod-name with the name of your Pod.

To resolve the status of the pod in the output, see How do I troubleshoot the pod status in Amazon EKS?

Q: I received the following error message: "Conflicts found when trying to apply. Will not continue to due to resolve conflicts mode." How do I troubleshoot this error?

Write the configuration in a JSON file. Then, apply the file to the add-on. For more information, see How do I prevent configuration conflicts when I create or update my Amazon EKS managed add-ons?

Q: How do I customize the configuration of my Amazon EKS add-on?

To create a custom configuration for your add-on, use the ConfigurationValue parameter in the CreateAddon API.

To check the configuration options for the CoreDNS add-on, run the describe-addon command:

aws eks describe-addon-configuration --addon-name coredns --addon-version v1.9.3-eksbuild.2 --query configurationSchema --output text | jq

Example output:

{
  "$ref": "#/definitions/Coredns",
  "$schema": "http://json-schema.org/draft-06/schema#",
  "definitions": {
    "Coredns": {
      "additionalProperties": false,
      "properties": {
        "computeType": {
          "type": "string"
        },
        "corefile": {
          "description": "Entire corefile contents to use with installation",
          "type": "string"
        },
        "nodeSelector": {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        "replicaCount": {
          "type": "integer"
        },
        "resources": {
          "$ref": "#/definitions/Resources"
        }
      },
      "title": "Coredns",
      "type": "object"
    },
    "Limits": {
      "additionalProperties": false,
      "properties": {
        "cpu": {
          "type": "string"
        },
        "memory": {
          "type": "string"
        }
      },
      "title": "Limits",
      "type": "object"
    },
    "Resources": {
      "additionalProperties": false,
      "properties": {
        "limits": {
          "$ref": "#/definitions/Limits"
        },
        "requests": {
          "$ref": "#/definitions/Limits"
        }
      },
      "title": "Resources",
      "type": "object"
    }
  }
}

The configurationSchema element in the output provides the configurable elements for the selected version of the CoreDNS add-on.

To update this add-on, specify the custom configuration according to the JSON schema. For example, to help schedule the CoreDNS deployment pods over a specific set of nodes, you can customize the selector\_value in the nodeSelector parameter.

Example:

{
    "nodeSelector": {
        "selector\_key": "selector\_value"
    }
}

Q: When I try to create or update an add-on with a custom configuration, why do I receive the following error: "ConfigurationValue provided in request is not supported: Json schema validation failed with error"?

The following configuration causes this error:

...
"Limits":
    { 
        "cpu":"100m", 
        "memory":"500Mi"
    }
...

Confirm that your advanced configuration follows the format of configurationSchema that the add-on version supports. To specify the resource quotas and requests for the CoreDNS add-on, run the following schema:

...
{
   "resources": {
        "limits": {
            "cpu": "200m",
            "memory": "200Mi",
        },
        "requests": {
            "cpu": "100m",
            "memory": "100Mi"
        }
    }
}
...

Q: Why did Amazon EKS revert my add-on JSON schema with custom parameters to the default parameters after I updated the add-on?

When you don't include the customized parameters for the add-on in the configurationValues field during the UpdateAddon API operation, the add-on reverts to the default parameters.

To maintain your edits to the configuration when you update the add-on, take one of the following actions:

Include the customized parameters in the configurationValues parameter during every UpdateAddon API operation.

-or-

Use the --resolve-conflicts PRESERVE option in your UpdateAddon operation.

Q: How do I check if an add-on is Amazon EKS managed or self-managed?

To check the type of add-on that's deployed in your cluster, run the AWS CLI describe-addon command:

aws eks describe-addon --cluster-name example-cluster --addon-name example-addon --query addon.addonVersion --output text

Note: Replace example-cluster with your cluster's name and example-addon with your add-on's name.

If the output provides information about your add-on, then Amazon EKS manages the add-on. If you receive an error message in the output, then the add-on is self-managed.

Q: How do I migrate the self-managed add-on in my cluster to an Amazon EKS add-on?

Create the Amazon EKS add-on with the appropriate conflict resolution method.

When you create the Amazon EKS add-on, you can pass your custom configuration in the configurationSchema field.

To maintain the in-cluster configuration changes, use the PRESERVE option when you update or delete an add-on. To maintain the changes that the Kubernetes API made to the fields that the Amazon EKS add-on doesn't manage, use the PRESERVE option. If the schema doesn't support this managed field, then you can manually add the customization in the add-on deployment or DaemonSet. Then, use the PRESERVE option for the next update operation.

When you choose OVERWRITE for the conflict resolution method, Amazon EKS reverts the customized settings on the add-on and overwrites your values with its default values.

Q: How do I migrate an Amazon EKS add-on to a self-managed add-on?

You must remove the Amazon EKS add-on from your Amazon EKS cluster, and then run the delete-addon command:

aws eks delete-addon --cluster-name example-cluster --addon-name example-addon --preserve

Note: Replace example-cluster with your cluster's name and example-addon with your add-on's name. Use the --preserve flag to retain the underlying Kubernetes resources.