Deploying PDK Providers

info

To deploy a PDK Provider, you'll need to have installed the cf CLI, and have valid AWS credentials in your terminal environment.

PDK Providers are packaged and deployed as AWS CloudFormation templates. These templates contain:

1. An AWS Lambda function which contains the code to run the Provider. This is called the Handler.
2. An AWS IAM role for the Handler, called the Handler Role.
3. An AWS IAM role which allows Common Fate to invoke the Lambda, called the Invoke Role.

Quickstart

To view the full process on deploying a PDK provider, see the section below.

First, make sure you are logged into Common Fate by running cf oss login. To quickly and interactively deploy a new PDK Provider, run the following command:

cf oss provider deploy

This command will walk you through the deployment and configuration process for the Handler, and will provision a CloudFormation template which will create AWS resources. The command will prompt you to bootstrap your AWS environment if it has not been bootstrapped already.

The command performs the following actions:

1. Ensures your AWS environment is bootstrapped.
2. Copies the Provider CloudFormation template and Lambda files from the Provider Registry to the bootstrap S3 bucket.
3. Deploys the CloudFormation template for the Handler.
4. Registers the Handler with Common Fate.
5. Creates a Target Group to to use with Access Rules
6. Links the Handler to the Target Group.

When running this command, you should see an output similar to the below:

Example output for the `cf oss provider deploy` commnad

❯ cf oss provider deploy --common-fate-aws-account 123456789012
? The Provider to deploy common-fate/cloudwatch-log-groups
? The version of the Provider to deploy v0.2.1
[i] This Provider will grant access to LogGroup targets
[i] Copying provider assets from the registry to the bootstrap bucket...
[i] Copied common-fate-bootstrap-assets-1234567abcedef/registry.commonfate.io/v1alpha1/providers/common-fate/cloudwatch-log-groups/v0.2.1/handler.zip
[i] Copied common-fate-bootstrap-assets-1234567abcedef/registry.commonfate.io/v1alpha1/providers/common-fate/cloudwatch-log-groups/v0.2.1/cloudformation.json
[✔] Provider assets copied to the bootstrap bucket
[i] This Provider requires configuration
? cloudwatch_read_role_arn: arn:aws:iam::123456789012:role/pdk-common-fate-cloudwatch-cloudwatch-read
[i] Setting CloudFormation parameter CloudwatchReadRoleArn=arn:aws:iam::123456789012:role/pdk-common-fate-cloudwatch-cloudwatch-read
? cloudwatch_regions: us-west-2
[i] Setting CloudFormation parameter CloudwatchRegions=us-west-2
? sso_identity_store_id: d-1234567abcd
[i] Setting CloudFormation parameter SsoIdentityStoreId=d-1234567abcd
? sso_instance_arn: arn:aws:sso:::instance/ssoins-1234567890abcd
[i] Setting CloudFormation parameter SsoInstanceArn=arn:aws:sso:::instance/ssoins-1234567890abcd
? sso_region: ap-southeast-2
[i] Setting CloudFormation parameter SsoRegion=ap-southeast-2
? sso_role_arn: arn:aws:iam::351460274277:role/pdk-common-fate-cloudwatch-aws-sso-provision
[i] Setting CloudFormation parameter SsoRoleArn=arn:aws:iam::351460274277:role/pdk-common-fate-cloudwatch-aws-sso-provision
[i] Deploying CloudFormation stack for Handler 'cf-handler-common-fate-cloudwatch-log-groups'
[i] Final stack status: CREATE_COMPLETE
[i] Deployment completed for HandlerID cf-handler-common-fate-cloudwatch-log-groups
[i] Creating a Target Group 'common-fate-cloudwatch-log-groups' to route Access Requests to the Handler
[✔] Target Group created: common-fate-cloudwatch-log-groups
[✔] Successfully registered Handler 'cf-handler-common-fate-cloudwatch-log-groups' with Common Fate
[✔] Successfully linked Handler 'cf-handler-common-fate-cloudwatch-log-groups' with Target Group 'common-fate-cloudwatch-log-groups'
[i] Waiting for Handler to become healthy...
[!] Handler is not healthy yet diagnostics:[{Code: Level:INFO Message:offline: lambda cannot be reached/invoked}]
[!] Handler is not healthy yet diagnostics:[{Code: Level:INFO Message:offline: lambda cannot be reached/invoked}]
[!] Handler is not healthy yet diagnostics:[{Code: Level:INFO Message:offline: lambda cannot be reached/invoked}]
[✔] Handler 'cf-handler-common-fate-cloudwatch-log-groups' is healthy

Removing a Handler

To uninstall the provider and its associated items, run the following command:

cf oss provider destroy --handler-id <handler-id> --target-group-id <target-group-id> --delete-cloudformation-stack

Listing existing Providers

List all the existing providers in Provider Registry by running:

cf oss provider list

You can quickly view a Provider's schema by running:

curl https://api.registry.commonfate.io/v1alpha1/providers/common-fate/aws/v0.2.0

Step-by-step

Running cf oss provider deploy walks through the deployment process interactively. If you prefer, you can run commands individually to deploy a Provider.

1. Copying assets

To copy the Provider assets to your bootstrap bucket, run the following command:

cf oss provider bootstrap --id <provider-id> --bootstrap-bucket=DEPLOYMENT_BUCKET

Here, the provider-id is the complete provider information including the publisher and version information. The format should take the following shape:

publisher/name@version

For example, common-fate/aws@v.0.2.0 means publisher is common-fate, name is aws, and version is v.0.2.0.

2. Creating target groups

Create a new Target Group for your Provider by running:

cf oss targetgroup create --id <enter_a_unique_targetgroup_identifier> --schema-from <provider-id>

3. Creating the Handler

Create a new Handler for your Provider by running:

cf oss handler register --id <enter_a_unique_handler_identifier> --aws-region <your_aws_region> --aws-account <your_aws_accound_id>

4. Target group linking

Link your Target Group with a Handler by running:

cf oss targetgroup link --target-group <target_group_id> --handler <handler_id> --kind <kind_name>

5. Deployment

You are now ready to deploy the CloudFormation stack for your Handler. To interactively enter all the required CloudFormation parameters, run the following command:

cf oss provider generate cloudformation-create

Alternatively, you can prefill these fields in the following command:

cf oss cloudformation generate cloudformation-create --provider-id <provider_id> --handler-id <handler_id> --region <aws_region>

Both will generate the aws cloudformation create-stack command.

Validating a Deployed Provider

To check the status of your Handler, run the following command:

cf oss handler validate --id <handler_id> --aws-region <region> --runtime aws-lambda