English / 日本語

Ghost String Parameter for CDK

Provides access control over parameters in Parameter Store on AWS Systems Manager.

This library is supposed to be combined with the AWS Cloud Development Kit (CDK) version 2.

Installation

npm install https://github.com/codemonger-io/cdk-ghost-string-parameter.git#v0.2.0

Installing from GitHub Packages

Every time commits are pushed to the main branch, a developer package is published to the npm registry managed by GitHub Packages. A developer package bears the next release number but followed by a dash (-) plus the short commit hash; e.g., 0.2.0-abc1234 where abc1234 is the short commit hash of the commit used to build the package (snapshot). You can find developer packages here.

Configuring a GitHub personal access token

To install a developer package, you need to configure a classic GitHub personal access token (PAT) with at least the read:packages scope. Below briefly explains how to configure a PAT. Please refer to the GitHub documentation for more details.

Once you have a PAT, please create a .npmrc file in your home directory with the following content:

//npm.pkg.github.com/:_authToken=$YOUR_GITHUB_PAT

Please replace $YOUR_GITHUB_PAT with your PAT.

In the root directory of your project, create another .npmrc file with the following content:

@codemonger-io:registry=https://npm.pkg.github.com

Then you can install a developer package with the following command:

npm install @codemonger-io/[email protected]

Please replace abc1234 with the short commit hash of the snapshot you want to install.

Example

The only class this library provides is GhostStringParameter. Here is an example to use it:

import { GhostStringParameter } from '@codemonger-io/cdk-ghost-string-parameter';
import { aws_iam as iam } from 'aws-cdk-lib';
import { Construct } from 'constructs';

class SampleConstruct extends Construct {
    readonly parameter: GhostStringParameter;

    constructor(scope: Construct, id: string) {
        super(scope, id);

        this.parameter = new GhostStringParameter(this, {
            parameterName: '/parameters/SAMPLE_PARAMETER'
        });
    }

    grantReadParameter(grantee: iam.IGrantable): iam.Grant {
        return this.parameter.grantRead(grantee);
    }
}

API Documentation

You can find the API documentation in api-docs/markdown.

Motivation

The CDK provides aws-cdk-lib.aws_ssm.StringParameter (StringParameter) that represents a parameter in Parameter Store on AWS Systems Manager. With StringParameter, you can control access to the parameter via the API like grantRead. However, to use StringParameter, you have to

• provision the parameter in the CDK stack
• or bind it to an existing parameter

Unfortunately, you cannot use StringParameter if you want to create the parameter in the futer after the CDK stack is deployed. If you want to control access to a parameter that does not exist at deployment without provisioning it, this library could help you.

Development

Resolving dependencies

pnpm install --frozen-lockfile

Building

pnpm build

Generating the API documentation

pnpm build:doc