Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Auth doc: update IRSA example with DeploymentRuntimeConfig #1321

Merged
merged 2 commits into from
May 23, 2024
Merged

Auth doc: update IRSA example with DeploymentRuntimeConfig #1321

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d78a4bd
Auth doc: update IRSA example with `DeploymentRuntimeConfig`
ytsarev May 23, 2024
815ec39
Update marketplace facing documentation with DeploymentRuntimeConfig
ytsarev May 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 14 additions & 16 deletions AUTHENTICATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,15 @@ configured by means of `aws.upbound.io/v1beta1/ProviderConfig` resources.

The authentication mechanism to be used can be selected by setting the
`spec.credentials.source` field of the `ProviderConfig` to one of the following
values:
values:
- `Secret`
- `IRSA`
- `WebIdentity`
to configure long-term credentials, IRSA and authentication with an assumed Web
identity, respectively.

If no authentication mechanism is specified, the default is to use the
`Secret` authentication mechanism.
`Secret` authentication mechanism.

*Note*: Please note that with Upbound managed control-planes (MCP), we will only support
the `Secret` authentication mechanism with `provider-aws` until EKS clusters can
Expand Down Expand Up @@ -108,30 +108,28 @@ metadata:

Thus, we need to have the `ServiceAccount` under which `provider-aws` is running
annotated with the key `eks.amazonaws.com/role-arn`, and this can be accomplished
in a number of ways. One approach is to use a `ControllerConfig` while
in a number of ways. One approach is to use a `DeploymentRuntimeConfig` while
installing the provider:

```yaml
apiVersion: pkg.crossplane.io/v1alpha1
kind: ControllerConfig
apiVersion: pkg.crossplane.io/v1beta1
kind: DeploymentRuntimeConfig
metadata:
name: irsa-controllerconfig
annotations:
eks.amazonaws.com/role-arn: arn:aws:iam::111122223333:role/iam-role-name
name: irsa-drc
spec:
podSecurityContext:
fsGroup: 2000
serviceAccountTemplate:
metadata:
annotations:
eks.amazonaws.com/role-arn: arn:aws:iam::111122223333:role/iam-role-name
---
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-aws
name: upbound-provider-aws-ec2
spec:
package: xpkg.upbound.io/upbound/provider-aws:v0.4.0
packagePullSecrets:
- name: package-pull-secret
controllerConfigRef:
name: irsa-controllerconfig
package: xpkg.upbound.io/upbound/provider-aws-ec2:v1.4.0
runtimeConfigRef:
name: irsa-drc
```

After the `ServiceAccount` under which `provider-aws` is running is annotated,
Expand Down
87 changes: 43 additions & 44 deletions docs/family/Configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,8 +163,8 @@ An IRSA configuration requires multiple components:
* Creating an IAM policy granting the AWS provider access to AWS resources.
* Creating an IAM role for the AWS provider to associate with the AWS provider.
* Creating a Kubernetes service account.
* Create a `ControllerConfig` to associate the IAM role ARN.
* Apply the `ControllerConfig` to the `Provider`.
* Create a `DeploymentRuntimeConfig` to associate the IAM role ARN.
* Apply the `DeploymentRuntimeConfig` to the `Provider`.
* Instruct the `ProviderConfig` to use `IRSA` credentials.

<!-- Disable heading acronym rule to ignore "OIDC" -->
Expand Down Expand Up @@ -199,10 +199,10 @@ $ aws iam list-open-id-connect-providers
```

##### Create an IAM policy
Define the actions the AWS provider can take by creating an IAM policy.
Define the actions the AWS provider can take by creating an IAM policy.

For example, here is a custom IAM policy to enable `SystemAdministrator` level
access.
access.
```json
{
"Version": "2012-10-17",
Expand All @@ -215,15 +215,15 @@ access.
]
}
```
Apply the policy using the AWS command-line command
Apply the policy using the AWS command-line command
```shell
aws iam create-policy \
--policy-name <new policy name> \
--policy-document file://<policy json file>
```

For example, to create a new policy named `custom-irsa-policy` from a policy
file named `custom-policy.json`:
file named `custom-policy.json`:
```shell
$ aws iam create-policy --policy-name custom-irsa-policy --policy-document file://custom-policy.json
{
Expand Down Expand Up @@ -256,32 +256,32 @@ policy and generate a service account. You **must** change the role trust policy
after creating it with `eksctl`.

To use `eksctl` to create a new service account and IAM role use the command
`eksctl create iamserviceaccount`.
`eksctl create iamserviceaccount`.

```shell
eksctl create iamserviceaccount \
--name <kubernetes service account name> \
--role-name <IAM role name> \
--cluster <the name of the EKS cluster>
--cluster <the name of the EKS cluster>
--attach-policy-arn <the ARN of the policy to apply> \
--namespace upbound-system \
--approve
```

| Configuration option | Description |
| Configuration option | Description |
| ---- | ---- |
| `--name` | The name of the Kubernetes service account to create. |
| `--role-name` | The name of the AWS IAM role to create. |
| `--role-name` | The name of the AWS IAM role to create. |
| `--cluster` | The name of the EKS cluster. |
| `--attach-policy-arn` | The ARN of the policy to attach to this service account and role. |
| `--attach-policy-arn` | The ARN of the policy to attach to this service account and role. |
| `--namespace` | The namespace to create the Kubernetes service account in. This must be the same namespace as Universal Crossplane. (The Universal Crossplane default namespace is `upbound-system`.) |

For example, to create a new service account with the configuration:

| Configuration option | Configuration value |
| Configuration option | Configuration value |
| ---- | ---- |
| `--name` | `my-upbound-sa` |
| `--role-name` | `eks-test-role` |
| `--role-name` | `eks-test-role` |
| `--cluster` | `upbound-docs` |
| `--attach-policy-arn` | `arn:aws:iam::000000000000:policy/custom-irsa-policy` |
| `--namespace` | `upbound-system` |
Expand Down Expand Up @@ -325,7 +325,7 @@ Tokens: my-upbound-sa-token-spq5k
Events: <none>
```

Confirm the attachment between the IAM policy and new IAM role with the command
Confirm the attachment between the IAM policy and new IAM role with the command
```shell
aws iam list-attached-role-policies \
--role-name <role name> \
Expand Down Expand Up @@ -373,11 +373,11 @@ $ aws iam get-role \
```
##### Update the IAM role
The IAM role created by `eksctl` doesn't have the correct `Conditions` for the
AWS provider.
AWS provider.

Update the role `Trust relationship`.
Update the role `Trust relationship`.

Use the output of `aws iam-get role` as a starting template.
Use the output of `aws iam-get role` as a starting template.

* Replace the `Condition.StringEquals` with `Condition.StringLike`.
```shell
Expand All @@ -387,14 +387,14 @@ Use the output of `aws iam-get role` as a starting template.

* Replace the body of the new `Condition.StringLike` with the provider string.
First, get the `OIDC issuer` with the command `aws eks decribe-cluster --name
<cluster-name>`.
<cluster-name>`.

For example,
For example,
```shell
$ aws eks describe-cluster --name upbound-docs --query "cluster.identity.oidc.issuer" --output text | sed -E 's_^https?://__'
oidc.eks.us-east-2.amazonaws.com/id/266A01FA1DBF8083FA1C23EB7D4736E4
```
Use this value to build the new contents, in the form:
Use this value to build the new contents, in the form:
`"<oidc issuer>:sub": "system:serviceaccount:<Universal Crossplane
namespace>:provider-aws-*"`

Expand Down Expand Up @@ -443,10 +443,10 @@ aws iam update-assume-role-policy \
--policy-document file://role.json
```

##### Create a ControllerConfig
A `ControllerConfig` creates settings used by the `Provider` deployment.
##### Create a DeploymentRuntimeConfig
A `DeploymentRuntimeConfig` creates settings used by the `Provider` deployment.

For IRSA, the `ControllerConfig` provides an `annotation` of the ARN of the role
For IRSA, the `DeploymentRuntimeConfig` provides an `annotation` of the ARN of the role
used by the Kubernetes service account.

First, use `kubectl describe service-account <name> -n upbound-system` to get
Expand All @@ -466,37 +466,36 @@ Tokens: my-upbound-sa-token-spq5k
Events: <none>
```

The `Annotations` value is the input for the `ControllerConfig`.

_Note:_ the `ControllerConfig` required for IRSA configuration doesn't require a
`spec` body.
The `Annotations` value is the input for the `DeploymentRuntimeConfig`.

```yaml
apiVersion: pkg.crossplane.io/v1alpha1
kind: ControllerConfig
apiVersion: pkg.crossplane.io/v1beta1
kind: DeploymentRuntimeConfig
metadata:
name: irsa-controllerconfig
annotations:
eks.amazonaws.com/role-arn: arn:aws:iam::000000000000:role/eks-test-role
name: irsa-drc
spec:
serviceAccountTemplate:
metadata:
annotations:
eks.amazonaws.com/role-arn: arn:aws:iam::000000000000:role/eks-test-role
```

Apply the `ControllerConfig` with `kubectl apply -f` and verify the installation
with `kubectl get controllerconfig`.
Apply the `DeploymentRuntimeConfig` with `kubectl apply -f` and verify the installation
with `kubectl get deploymentruntimeconfigs`.

```shell
$ kubectl apply -f controller-config.yml
$ kubectl get controllerconfig
$ kubectl apply -f deployment-runtime-config.yml
$ kubectl get deploymentruntimeconfigs
NAME AGE
irsa-controllerconfig 6s
irsa-drc 6s
```

##### Create a Provider
The `Provider` object references the `ControllerConfig` to use the AWS IAM role
The `Provider` object references the `DeploymentRuntimeConfig` to use the AWS IAM role
ARN.

The `Provider.spec.controllerConfigRef.name` must match the
`ControllerConfig.name` value.
The `Provider.spec.runtimeConfigRef.name` must match the
`DeploymentRuntimeConfig.metadata.name` value.

```yaml
apiVersion: pkg.crossplane.io/v1
Expand All @@ -505,8 +504,8 @@ metadata:
name: provider-aws-s3
spec:
package: xpkg.upbound.io/upbound/provider-aws-s3:latest
controllerConfigRef:
name: irsa-controllerconfig
runtimeConfigRef:
name: irsa-drc
```

Apply the `Provider` object with `kubectl apply -f` and verify with `kubectl get
Expand All @@ -524,9 +523,9 @@ _Note_: it may take up to five minutes for the provider `HEALTHY` value to be

##### Create a ProviderConfig
The `ProviderConfig` explicitly configures the official AWS provider-family to use
`IRSA` authentication.
`IRSA` authentication.

Define the `ProviderConfig.spec.credentials.source` as `IRSA`.
Define the `ProviderConfig.spec.credentials.source` as `IRSA`.

```yaml
apiVersion: aws.upbound.io/v1beta1
Expand Down
Loading