Best practice for checking if desired OIDC Identity Provider already exists during synth

[LiamGraham]

We have a stack that provisions an IAM role used to allow AWS SDK commands to be run from a GitHub workflow. This is facilitated by an OpenID Connect (OIDC) provider configured for our GitHub organisation. This provider is also created as part of this stack. However, it is only possible to create one OIDC provider for a given URL (https://token.actions.githubusercontent.com in this case) per AWS account, and attempting to run this same CDK stack multiple times leads to a deployment error.

This is the code in question:

const identityProvider = new iam.OpenIdConnectProvider(this, 'GithubProvider', {
  url: 'https://token.actions.githubusercontent.com',
  thumbprints: ['<thumbprint>'],
  clientIds: ['<clientId>']
});

We would like to be able to first check for the existence of this OIDC provider in our CDK, and only create a new provider if one has not been created previously. As this requires making an async AWS SDK call to retrieve the provider ARN, this is not immediately possible given the constructor-based design of CDK.

What is the recommended best practice for checking for the existence of a singleton resource, such as this OIDC provider, as part of the build process?

[pahud]

This is interesting. You actually can check the existence of a singleton resource with custom resource, but you can't conditionally create a dependent resource based on the condition by reference to an attribute of a custom resource. I actually can't figure out any good practice to make it possible 100% within CDK app.

However, you can consider to write a wrapper script to deploy your cdk like this:

#!/bin/bash

function check_if_already_exists_function() {
    # check the existence with AWS CLI
}

oidcp_exist=$(check_if_already_exists_function)
npx cdk deploy -c oidcp_exist=${oidcp_exist}

And you can conditionally create the iam.OpenIdConnectProvider resource by checking the context variable passed in.

[ChenKuanSun]

Considering use ssm to store Arn for this.

If Arn, just create references from Arn, else create a new one.

[pahud]

@ChenKuanSun @LiamGraham

Yes the general practice is to store the state in ssm parameter store or context variable so your CDK application can simply tell if the oidc provider is already there.

[steffenstolze]

@pahud @ChenKuanSun @LiamGraham

I'm facing the same problem that specific resources can only be created once, e.g. a Custom Domain Name for API Gateway.

CDK standard behaviour will result in a "The domain name you provided already exists." error when you try to deploy the stack again, e.g. because you made changes, added new API resources or methods, etc.

The way I see it, there are basically three ways to handle this:

1) Create the problematic resources using a Lambda backed CustomResource

Since the existence of a specific DomainName can be determined by AWS SDK API calls using the name, e.g. api.example.com you could store those names in an .env file or SSM parameter even before deploying the app.

Within a Lambda function of a CustomResource you could check for event.RequestType === 'Create' and use AWS SDK to check for the DomainName by name (from.env). If it doesn't exist, create it using AWS SDK. If it already exist, do nothing.

Pro

• makes 100% sure that CDK knows if the resource exists or not, since you don't rely on some saved state but a live API call and result

Con

• Lambda backed CustomResource introduces a bit of an overhead into your CDK app / stack

2) Wrap the whole stack in async IIFE and check for existing resources with AWS SDK within the CDK stack

This is basically the same approach as 1) but with less overhead.

You can wrap your whole stack in an async IFEE like this and use AWS SDK (within your CDK App) to check for the resource existence:

export class ApiStack extends Stack {
	constructor(scope: Construct, id: string, props?: StackProps) {
		super(scope, id, props);

		(async () => {
			const api = new apigateway.RestApi(this, `${process.env.STACK_NAME}-${process.env.STACK_ENV}_api`, {
				description: 'Customer API',
				deployOptions: {
					stageName: `${process.env.STACK_ENV}`
				},
				endpointConfiguration: { types: [EndpointType.REGIONAL] }
			});

                        // check if DomainName exists with AWS SDK
			let apiGatewayDomainExists = false;
			const sdk_apigw = new sdk.APIGateway();
			try {
				await sdk_apigw.getDomainName({ domainName: `${process.env.DOMAIN}` }).promise();
				apiGatewayDomainExists = true;
				console.log(`API Gateway custom domain "${process.env.DOMAIN}" does exist and will NOT be created.`);
			} catch (error) {
				console.log(`API Gateway custom domain "${process.env.DOMAIN}" does not exist and will be created.`);
			}

			if (!apiGatewayDomainExists) {
				const domainName = new apigateway.DomainName(this, `${process.env.STACK_NAME}-${process.env.STACK_ENV}_domain`, {
					domainName: `${process.env.DOMAIN}`,
					certificate: Certificate.fromCertificateArn(this, `${process.env.STACK_NAME}-${process.env.STACK_ENV}_cert`, `${process.env.AWS_ACM_CERT_ARN}`),
					endpointType: EndpointType.REGIONAL,
					mapping: api
				});
				domainName.applyRemovalPolicy(RemovalPolicy.RETAIN);
				new CfnOutput(this, `${process.env.STACK_NAME}-${process.env.STACK_ENV}_api_gateway_domain_name`, { value: domainName.domainNameAliasDomainName });
			}

                        ....
		})();
	}
}

Pro

• makes 100% sure that CDK knows if the resource exists or not, since you don't rely on some saved state but a live API call and result
• way less overhead than a CustomResource

Con

• It feels like an anti-pattern and could make people say "This is not how CDK works!!!!111"

3) Store the CDK state SSM and retrieve / evaluate state when re-deploying

Following this approach: https://bobbyhadz.com/blog/aws-cdk-ssm-parameters

you could store the state (e.g. "DomainNameResourceCreated" in a SSM parameter.

The creation itself could depend on the evaluation of that SSM parameter directly in the CDK stack.

if(domainNameCreatedParam) {
....
}

Pro

• should work in general and doesn't feel hacky

Con

• CDK can't make sure that the resource exists or not, since the resources could have been deleted in the console and the SSM state would be wrong

I'm using the second approach with async IIFE, since it works well and doesn't introduce overhead.

What's your recommendation / approach?

Thanks!

[pahud]

@steffenstolze Sorry for late response but I love your thoughts above.

I personally prefer to "check with CLI or API call and store the state" immediately before I cdk deploy it. Usually I will write a wrapper script(bash or python) to check the latest state of everything and persist to somewhere so my CDK app will be aware of that and determine its behavior from the state. I have seen customers using the following options:

1. .env files

Some customers may generate .env files for ts-based CDK and read in all .env files with dotenv module. The CDK application will be able to have a bunch of env vars available and determine if it should conditionally create any resources. The .env files can be pre-generated, generated on-the-fly or preconfigured by a different team and managed in the git repo. I know some customers update their config or status in DynamoDB table and generate the .env files from the table before cdk deploy.

2. shared ssm parameters

While .env files are file based, SSM parameters within the same AWS account can be shared across different stacks/apps. Some customers may have a DevOps team responsible for the SSM parameters as the producer role while others deploying CDK as the consumer. It's like the state-of-the-truth where multiple CDK stacks/apps can share the same state generated by the state maintainer or infra/ops team.

3. context variables

Some customers like InfuseAI tend to check the external state and pass to CDK as context variables. Check out this interesting sample by them. With a custom deployment wrapper like this, you are very free and flexible to do anything(CLI or API call) without writing async typescript code in your CDK App. Some ops/infra folks might be more comfortable with that.

[trondhindenes]

we separate "singleton per account" things in a different stack than for example "stack-per-eks-cluster" items. We use dependency (stack.add_dependency(parent_stack)) to build a "graph" of stacks and how they depend on each other - it might be something like this:

account-1
├── cluster1
│   └── resources-cluster1
└── cluster2
    └── resources-cluster2
account-2
└── cluster3
    └── resources-cluster3

when running "cdk ls" we have code that will dynamically look for the various stack types and build the dependency graph. For example, we know that an eks cluster provisioned in account-1 will need to depend on the "account-1 stack". Similarly, the "resources-cluster2" stack will depend on the "cluster2" stack.

This will only work if the stacks can live together in the same cdk app. If not, we'd still probably provision the oidc provider as an "account-stack" item, and store any data that needs retrieving in a well-known ssm path so that other apps can retrieve it. We do this for EKS oidc provider arns, which are needed by app stacks to construct the correct iam role trust policy.