Skip to content

Commit 7568d7d

Browse files
zjaco13zjaco13
committed
add docs and update capabilities api
1 parent 36faac6 commit 7568d7d

File tree

15 files changed

+572
-84
lines changed

15 files changed

+572
-84
lines changed

‎docs/capabilities/ack-capability.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# ACK Capability
2+
3+
The [ACK capability](https://docs.aws.amazon.com/eks/latest/userguide/capabilities.html) enables management of AWS resources using Kubernetes APIs. It continuously reconciles the desired state with the actual state in AWS, correcting any drift. ACK supports cross-account and cross-region resource management.
4+
5+
This is the AWS-managed alternative to the self-managed [AckAddOn](../addons/ack.md). Using both on the same cluster will result in a conflict error.
6+
7+
## Usage
8+
9+
```typescript
10+
import * as blueprints from '@aws-quickstart/eks-blueprints';
11+
12+
const stack = blueprints.EksBlueprint.builder()
13+
.version("auto")
14+
.capabilities({
15+
ack: new blueprints.capabilities.AckCapability(),
16+
})
17+
.build(app, 'my-cluster');
18+
```
19+
20+
## Configuration
21+
22+
| Property | Type | Default | Description |
23+
|----------|------|---------|-------------|
24+
| `capabilityName` | `string` | `blueprints-ack-capability` | Name for the capability resource |
25+
| `roleArn` | `string` | Auto-created | Existing IAM role ARN to use |
26+
| `policyName` | `string` | - | Custom managed policy name |
27+
| `policyDocument` | `iam.PolicyDocument` | - | Custom inline policy |
28+
| `tags` | `CfnTag[]` | - | CloudFormation tags |
29+
30+
The default IAM policy is `AdministratorAccess`. For production, scope this down to only the AWS services you need:
31+
32+
```typescript
33+
new blueprints.capabilities.AckCapability({
34+
policyName: "AmazonRDSFullAccess",
35+
})
36+
```

‎docs/capabilities/argocd-capability.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# ArgoCD Capability
2+
3+
The [ArgoCD capability](https://docs.aws.amazon.com/eks/latest/userguide/capabilities.html) enables GitOps-based continuous deployment, automatically syncing application resources to clusters from Git repositories. It integrates with AWS Identity Center for authentication and authorization.
4+
5+
This is the AWS-managed alternative to the self-managed [ArgoCDAddOn](../addons/argocd.md). Using both on the same cluster will result in a conflict error.
6+
7+
## Usage
8+
9+
```typescript
10+
import * as blueprints from '@aws-quickstart/eks-blueprints';
11+
12+
const stack = blueprints.EksBlueprint.builder()
13+
.version("auto")
14+
.capabilities({
15+
argocd: new blueprints.capabilities.ArgoCapability({
16+
idcInstanceArn: "arn:aws:sso:::instance/ssoins-1234567890abcdef",
17+
}),
18+
})
19+
.build(app, 'my-cluster');
20+
```
21+
22+
## Configuration
23+
24+
| Property | Type | Default | Description |
25+
|----------|------|---------|-------------|
26+
| `idcInstanceArn` | `string` | **Required** | AWS Identity Center instance ARN |
27+
| `idcManagedApplicationArn` | `string` | - | IDC managed application ARN |
28+
| `idcRegion` | `string` | - | IDC region |
29+
| `capabilityName` | `string` | `blueprints-argocd-capability` | Name for the capability resource |
30+
| `namespace` | `string` | `argocd` | Kubernetes namespace for ArgoCD |
31+
| `serverUrl` | `string` | - | ArgoCD server URL |
32+
| `networkAccessVpcEndpoints` | `IVpcEndpoint[]` | - | VPC endpoints for network access |
33+
| `roleMappings` | `Record<ArgoCDSsoRole, ...>` | - | SSO role-to-identity mappings |
34+
| `roleArn` | `string` | Auto-created | Existing IAM role ARN |
35+
| `tags` | `CfnTag[]` | - | CloudFormation tags |
36+
37+
The default IAM policy is `AWSSecretsManagerClientReadOnlyAccess`.
38+
39+
## Role Mappings
40+
41+
Map AWS Identity Center users or groups to ArgoCD RBAC roles. Two approaches:
42+
43+
**Simplified props:**
44+
```typescript
45+
new blueprints.capabilities.ArgoCapability({
46+
idcInstanceArn: "arn:aws:sso:::instance/ssoins-1234567890abcdef",
47+
roleMappings: {
48+
adminUsers: ["<sso-user-id>"],
49+
viewerGroups: ["<sso-group-id>"],
50+
editorUsers: ["<sso-user-id>"],
51+
},
52+
})
53+
```
54+
55+
**Builder methods:**
56+
```typescript
57+
new blueprints.capabilities.ArgoCapability({
58+
idcInstanceArn: "arn:aws:sso:::instance/ssoins-1234567890abcdef",
59+
})
60+
.addAdmin("<sso-user-id>", blueprints.SsoIdentityType.SSO_USER)
61+
.addViewer("<sso-group-id>", blueprints.SsoIdentityType.SSO_GROUP)
62+
.addEditor("<sso-user-id>", blueprints.SsoIdentityType.SSO_USER)
63+
```
64+
65+
Both approaches can be combined — mappings are merged at deploy time.
66+
67+
Available roles: `ADMIN`, `EDITOR`, `VIEWER`.

‎docs/capabilities/index.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# EKS Capabilities
2+
3+
[EKS Capabilities](https://docs.aws.amazon.com/eks/latest/userguide/capabilities.html) are fully managed cluster features that eliminate the need to install, maintain, and scale foundational cluster services. Each capability is an AWS resource that runs in EKS and is managed by AWS.
4+
5+
Available capabilities:
6+
7+
- **[ACK](ack-capability.md)** — Manage AWS resources using Kubernetes APIs
8+
- **[ArgoCD](argocd-capability.md)** — GitOps-based continuous deployment with AWS Identity Center integration
9+
- **[kro](kro-capability.md)** — Create custom Kubernetes APIs that compose multiple resources into higher-level abstractions
10+
11+
## Capabilities vs Addons
12+
13+
Capabilities are the AWS-managed equivalent of self-managed addons. They differ in that AWS handles installation, upgrades, scaling, and security patching. The blueprints framework automatically detects conflicts — if you add both a capability and its corresponding addon (e.g. `AckCapability` and `AckAddOn`), the build will fail with a conflict error.
14+
15+
## Usage
16+
17+
```typescript
18+
import * as blueprints from '@aws-quickstart/eks-blueprints';
19+
20+
const stack = blueprints.EksBlueprint.builder()
21+
.version("auto")
22+
.capabilities({
23+
ack: new blueprints.capabilities.AckCapability(),
24+
kro: new blueprints.capabilities.KroCapability(),
25+
})
26+
.build(app, 'my-cluster');
27+
```
28+
29+
Each capability key (`ack`, `argocd`, `kro`) can only appear once — the type system enforces this at compile time.
30+
31+
## IAM Roles
32+
33+
Each capability requires an IAM role with the `capabilities.eks.amazonaws.com` service principal. By default, the framework creates a role with the capability's default managed policy. You can customize this:
34+
35+
```typescript
36+
// Use a custom existing role
37+
new blueprints.capabilities.AckCapability({
38+
roleArn: "arn:aws:iam::123456789:role/my-custom-role",
39+
})
40+
41+
// Use a custom managed policy
42+
new blueprints.capabilities.AckCapability({
43+
policyName: "MyCustomAckPolicy",
44+
})
45+
46+
// Use an inline policy document
47+
new blueprints.capabilities.AckCapability({
48+
policyDocument: new iam.PolicyDocument({ ... }),
49+
})
50+
```

‎docs/capabilities/kro-capability.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# kro Capability
2+
3+
The [kro capability](https://docs.aws.amazon.com/eks/latest/userguide/capabilities.html) enables creation of custom Kubernetes APIs that compose multiple resources into higher-level abstractions. Platform teams can define reusable patterns for common resource combinations, enabling self-service with appropriate guardrails.
4+
5+
This is the AWS-managed alternative to the self-managed [KroAddOn](../addons/kro.md). kro itself does not require AWS IAM permissions — it orchestrates Kubernetes resources only. AWS resource creation is handled by controllers like ACK.
6+
7+
## Usage
8+
9+
```typescript
10+
import * as blueprints from '@aws-quickstart/eks-blueprints';
11+
12+
const stack = blueprints.EksBlueprint.builder()
13+
.version("auto")
14+
.capabilities({
15+
kro: new blueprints.capabilities.KroCapability(),
16+
})
17+
.build(app, 'my-cluster');
18+
```
19+
20+
## Configuration
21+
22+
| Property | Type | Default | Description |
23+
|----------|------|---------|-------------|
24+
| `capabilityName` | `string` | `blueprints-kro-capability` | Name for the capability resource |
25+
| `roleArn` | `string` | Auto-created | Existing IAM role ARN to use |
26+
| `policyName` | `string` | - | Custom managed policy name |
27+
| `policyDocument` | `iam.PolicyDocument` | - | Custom inline policy |
28+
| `tags` | `CfnTag[]` | - | CloudFormation tags |
29+
30+
No default IAM policy is attached since kro doesn't interact with AWS APIs directly.
31+
32+
## Using with ACK
33+
34+
kro is commonly paired with the ACK capability to create custom APIs that provision AWS resources:
35+
36+
```typescript
37+
const stack = blueprints.EksBlueprint.builder()
38+
.version("auto")
39+
.capabilities({
40+
ack: new blueprints.capabilities.AckCapability(),
41+
kro: new blueprints.capabilities.KroCapability(),
42+
})
43+
.build(app, 'my-cluster');
44+
```
45+
46+
See the [kro addon documentation](../addons/kro.md) for ResourceGraphDefinition examples.

‎examples/capabilities-test.ts‎

Lines changed: 12 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -8,30 +8,15 @@ const app = new cdk.App();
88

99
const account = process.env.CDK_DEFAULT_ACCOUNT;
1010
const region = process.env.CDK_DEFAULT_REGION;
11+
12+
// Must have identity center set up for ArgoCD Capability
1113
const identityCenterArn = process.env.AWS_IDENTITY_CENTER_ARN;
1214
const identityCenterUserId = process.env.AWS_IDENTITY_CENTER_USER_ID;
1315

14-
// Example customer issue reproduction:
1516
const addOns: Array<blueprints.ClusterAddOn> = [
1617
new blueprints.addons.EksPodIdentityAgentAddOn(),
17-
new blueprints.addons.AwsNetworkFlowMonitorAddOn()
1818
];
1919

20-
const capabilities: Array<blueprints.ClusterCapability> = [
21-
new blueprints.capabilities.AckCapability(),
22-
new blueprints.capabilities.ArgoCapability({
23-
idcInstanceArn: identityCenterArn!,
24-
roleMappings: {
25-
"ADMIN": [{
26-
identityId: identityCenterUserId!,
27-
identityType: blueprints.SsoIdentityType.SSO_USER
28-
}],
29-
30-
}
31-
}),
32-
new blueprints.capabilities.KroCapability(),
33-
]
34-
3520
const clusterProvider = new blueprints.GenericClusterProvider({
3621
authenticationMode: eks.AuthenticationMode.API_AND_CONFIG_MAP,
3722
managedNodeGroups: [{
@@ -45,7 +30,16 @@ const stack = blueprints.EksBlueprint.builder()
4530
.account(account)
4631
.region(region)
4732
.clusterProvider(clusterProvider)
48-
.capabilities(...capabilities)
33+
.capabilities({
34+
ack: new blueprints.capabilities.AckCapability(),
35+
argocd: new blueprints.capabilities.ArgoCapability({
36+
idcInstanceArn: identityCenterArn!,
37+
roleMappings: {
38+
adminUsers: [identityCenterUserId!],
39+
}
40+
}),
41+
kro: new blueprints.capabilities.KroCapability(),
42+
})
4943
.addOns(...addOns)
5044
.version("auto")
5145
.build(app, 'capabilities-debug-stack');

‎lib/addons/ack/index.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ import "reflect-metadata";
66
import { conflictsWithCapabilities, createNamespace, setPath, supportsX86 } from "../../utils";
77
import { HelmAddOn, HelmAddOnProps, HelmAddOnUserProps } from "../helm-addon";
88
import { AckServiceName, serviceMappings } from './serviceMappings';
9-
import { AckCapability } from '../../capabilities';
9+
import { CapabilityType } from '../../spi';
1010

1111
export * from "./serviceMappings";
1212

@@ -71,7 +71,7 @@ export class AckAddOn extends HelmAddOn {
7171
}
7272

7373

74-
@conflictsWithCapabilities(AckCapability.name)
74+
@conflictsWithCapabilities(CapabilityType.ACK)
7575
deploy(clusterInfo: ClusterInfo): Promise<Construct> {
7676
const cluster = clusterInfo.cluster;
7777
const context = clusterInfo.getResourceContext();

‎lib/addons/argocd/index.ts‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,6 @@ import { HelmAddOn, HelmAddOnUserProps } from '../helm-addon';
1212
import { ArgoApplication } from './application';
1313
import { createSecretRef } from './manifest-utils';
1414
import { GitRepositoryReference } from "../../spi";
15-
import * as capabilities from "../../capabilities";
1615

1716

1817
/**
@@ -120,7 +119,7 @@ export class ArgoCDAddOn implements spi.ClusterAddOn, spi.ClusterPostDeploy {
120119
/**
121120
* Implementation of the add-on contract deploy method.
122121
*/
123-
@conflictsWithCapabilities(capabilities.ArgoCapability.name)
122+
@conflictsWithCapabilities(spi.CapabilityType.ARGOCD)
124123
async deploy(clusterInfo: spi.ClusterInfo): Promise<Construct> {
125124
const namespace = createNamespace(this.options.namespace!, clusterInfo.cluster, true);
126125

‎lib/capabilities/ack-capability.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,6 @@ export class AckCapability extends Capability {
1919

2020
/** Default configuration for ACK capabilities */
2121
static readonly defaultProps: AckCapabilityProps= {
22-
useDefaultPolicy: true,
2322
capabilityName: "blueprints-ack-capability"
2423
};
2524

0 commit comments

Comments
 (0)