diff --git a/.spelling b/.spelling index 23cde6e8779..288a06c77c8 100644 --- a/.spelling +++ b/.spelling @@ -253,6 +253,7 @@ Ramlot RinkiyaKeDad Robusta Route53 +API_AssumeRoleWithWebIdentity Runtime roadmap SGX diff --git a/content/docs/configuration/acme/dns01/route53.md b/content/docs/configuration/acme/dns01/route53.md index e441b3b0c3c..55ae5c27892 100644 --- a/content/docs/configuration/acme/dns01/route53.md +++ b/content/docs/configuration/acme/dns01/route53.md @@ -188,11 +188,18 @@ Note that, as mentioned above, the pod is using `arn:aws:iam::XXXXXXXXXXX:role/c While [`kiam`](https://github.com/uswitch/kiam) / [`kube2iam`](https://github.com/jtblin/kube2iam) work directly with cert-manager, some special attention is needed for using the [IAM Roles for Service Accounts](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) feature available on EKS. -### OIDC provider +This feature uses Kubernetes `ServiceAccount` tokens to authenticate with AWS using the [API_AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html). -First follow the AWS documentation [Enabling IAM roles for service accounts on your cluster](https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html) to ensure that the OIDC provider for the EKS cluster is enabled. The OIDC information is needed to create the trust relationship for the cert-manager role below. +> **Note**: For using IRSA with cert-manager you must first enable the feature for your cluster. You can do this by +> following the [official documentation(https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html). -### IAM role trust policy +Because `ServiceAccount` tokens are used to authenticate there are two modes of operation, you can either use cert-manager's own `ServiceAccount` to authenticate or you can reference your own `ServiceAccount` within your `Issuer`/`ClusterIssuer` config. Each option is described below. + +### Using the cert-manager ServiceAccount + +In this configuration an IAM role is mapped to the cert-manager `ServiceAccount` allowing it to authenticate with AWS. The IAM role you map to the `ServiceAccount` will need permissions on any and all Route53 zones cert-manager will be using. + +#### IAM role trust policy The cert-manager role needs the following trust relationship attached to the role in order to use the IRSA method. Replace the following: @@ -224,7 +231,7 @@ The cert-manager role needs the following trust relationship attached to the rol **Note:** If you're following the Cross Account example above, this trust policy is attached to the cert-manager role in Account X with ARN `arn:aws:iam::XXXXXXXXXXX:role/cert-manager`. The permissions policy is the same as above. -### Service annotation +#### Service annotation Annotate the `ServiceAccount` created by cert-manager: @@ -257,3 +264,121 @@ securityContext: ``` **Note:** If you're following the Cross Account example above, modify the `ClusterIssuer` in the same way as above with the role from Account Y. + +### Referencing your own ServiceAccount within Issuer/ClusterIssuer config + +In this configuration you can reference your own `ServiceAccounts` within your `Issuer`/`ClusterIssuer` and cert-manager will issue itself temporary credentials using these `ServiceAccounts`. Because each issuer can reference a different `ServiceAccount` you can lock down permissions much more, with each `ServiceAccount` mapped to an IAM role that only has permission on the zones it needs for that particular issuer. + + +#### Creating a ServiceAccount + +In order to reference a `ServiceAccount` it must first exist. Unlike normal IRSA the `eks.amazonaws.com/role-arn` annotation is not required, however you may wish to set it as a reference. + +```yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + name: + annotation: + eks.amazonaws.com/role-arn: +``` + +#### IAM role trust policy + +For every `ServiceAccount` you want to use for AWS authentication you must first set up a trust policy. Replace the following: + +- `` with the AWS account ID of the EKS cluster. +- `` with the region where the EKS cluster is located. +- `` with the hash in the EKS API URL; this will be a random 32 character hex string (example: `45DABD88EEE3A227AF0FA468BE4EF0B5`) +- `` with the namespace of the `ServiceAccount` object. +- `` with the name of the `ServiceAccount` object. + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "sts:AssumeRoleWithWebIdentity", + "Principal": { + "Federated": "arn:aws:iam:::oidc-provider/oidc.eks..amazonaws.com/id/" + }, + "Condition": { + "StringEquals": { + "oidc.eks..amazonaws.com/id/:sub": "system:serviceaccount::" + } + } + } + ] +} +``` + +**Note:** If you're following the Cross Account example above, this trust policy is attached to the cert-manager role in Account X with ARN `arn:aws:iam::XXXXXXXXXXX:role/cert-manager`. The permissions policy is the same as above. + +#### RBAC + +In order to allow cert-manager to issue a token using your `ServiceAccount` you must deploy some RBAC to the cluster. Replace the following: + +- `` name of the `ServiceAccount` object. +- `` namespace of the `ServiceAccount` object. +- `` name of cert-managers `ServiceAccount` object, as created during cert-manager installation. +- `` namespace that cert-manager is deployed into. + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: -tokenrequest + namespace: +rules: + - apiGroups: [''] + resources: ['serviceaccounts/token'] + resourceNames: [''] + verbs: ['create'] +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: cert-manager--tokenrequest + namespace: +subjects: + - kind: ServiceAccount + name: + namespace: +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: -tokenrequest +``` + +#### Issuer/ClusterIssuer config + +Once you have completed the above you should have: +- An IAM role with permissions required to on the Route53 zone. +- A Kubernetes `ServiceAccount`. +- A trust policy to allow the Kubernetes `ServiceAccount` access to your IAM role. +- RBAC to allow cert-manager to issue a token using the Kubernetes `ServiceAccount`. + +You should be ready at this point to configure an Issuer to use the new `ServiceAccount`. You can see example config for this below: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: example +spec: + acme: + ... + solvers: + - selector: + dnsZones: + - "example.com" + dns01: + route53: + region: us-east-1 + role: # This must be set so cert-manager what role to attempt to authenticate with + auth: + kubernetes: + serviceAccountRef: + name: # The name of the service account created +``` \ No newline at end of file