Skip to content

API.md

Latest commit

 

History

History
1999 lines (1247 loc) · 75.7 KB

API.md

File metadata and controls

1999 lines (1247 loc) · 75.7 KB
Raw

API Reference

Constructs

CircleCiOidcProvider

This construct creates a CircleCI ODIC provider to allow AWS access from CircleCI jobs.

You'll need to instantiate this construct once per AWS account you want to use CircleCI OIDC with.

You can import a existing provider using CircleCiOidcProvider.fromOrganizationId.

To create a role that can be assumed by CircleCI jobs, use the CircleCiOidcRole construct.

Initializers 

import { CircleCiOidcProvider } from '@blimmer/cdk-circleci-oidc'

new CircleCiOidcProvider(scope: Construct, id: string, props: CircleCiOidcProviderProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props CircleCiOidcProviderProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
with Applies one or more mixins to this construct.
overrideLogicalId Overrides the auto-generated logical ID with a specific ID.
addDeletionOverride Syntactic sugar for addOverride(path, undefined).
addDependency Indicates that this resource depends on another resource and cannot be provisioned unless the other resource has been successfully provisioned.
addDependsOn Indicates that this resource depends on another resource and cannot be provisioned unless the other resource has been successfully provisioned.
addMetadata Add a value to the CloudFormation Resource Metadata.
addOverride Adds an override to the synthesized CloudFormation resource.
addPropertyDeletionOverride Adds an override that deletes the value of a property from the resource definition.
addPropertyOverride Adds an override to a resource property.
applyRemovalPolicy Sets the deletion policy of the resource based on the removal policy specified.
getAtt Returns a token for an runtime attribute of this resource.
getMetadata Retrieve a value value from the CloudFormation Resource Metadata.
obtainDependencies Retrieves an array of resources this resource depends on.
obtainResourceDependencies Get a shallow copy of dependencies between this resource and other resources in the same stack.
removeDependency Indicates that this resource no longer depends on another resource.
replaceDependency Replaces one dependency with another.
inspect Examines the CloudFormation resource and discloses attributes.
toString 
public toString(): string

Returns a string representation of this construct.

with 
public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

Mixins are applied in order. The list of constructs is captured at the start of the call, so constructs added by a mixin will not be visited. Use multiple with() calls if subsequent mixins should apply to added constructs.

mixinsRequired
  • Type: ...constructs.IMixin[]

The mixins to apply.

overrideLogicalId 
public overrideLogicalId(newLogicalId: string): void

Overrides the auto-generated logical ID with a specific ID.

newLogicalIdRequired
  • Type: string

The new logical ID to use for this stack element.

addDeletionOverride 
public addDeletionOverride(path: string): void

Syntactic sugar for addOverride(path, undefined).

pathRequired
  • Type: string

The path of the value to delete.

addDependency 
public addDependency(target: CfnResource): void

Indicates that this resource depends on another resource and cannot be provisioned unless the other resource has been successfully provisioned.

This can be used for resources across stacks (or nested stack) boundaries and the dependency will automatically be transferred to the relevant scope.

targetRequired
  • Type: aws-cdk-lib.CfnResource
addDependsOn 
public addDependsOn(target: CfnResource): void

Indicates that this resource depends on another resource and cannot be provisioned unless the other resource has been successfully provisioned.

targetRequired
  • Type: aws-cdk-lib.CfnResource
addMetadata 
public addMetadata(key: string, value: any): void

Add a value to the CloudFormation Resource Metadata.

[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/metadata-section-structure.html

Note that this is a different set of metadata from CDK node metadata; this metadata ends up in the stack template under the resource, whereas CDK node metadata ends up in the Cloud Assembly.](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/metadata-section-structure.html

Note that this is a different set of metadata from CDK node metadata; this metadata ends up in the stack template under the resource, whereas CDK node metadata ends up in the Cloud Assembly.)

keyRequired
  • Type: string
valueRequired
  • Type: any
addOverride 
public addOverride(path: string, value: any): void

Adds an override to the synthesized CloudFormation resource.

To add a property override, either use addPropertyOverride or prefix path with "Properties." (i.e. Properties.TopicName).

If the override is nested, separate each nested level using a dot (.) in the path parameter. If there is an array as part of the nesting, specify the index in the path.

To include a literal . in the property name, prefix with a \. In most programming languages you will need to write this as "\\." because the \ itself will need to be escaped.

For example,

cfnResource.addOverride('Properties.GlobalSecondaryIndexes.0.Projection.NonKeyAttributes', ['myattribute']);
cfnResource.addOverride('Properties.GlobalSecondaryIndexes.1.ProjectionType', 'INCLUDE');

would add the overrides

"Properties": {
  "GlobalSecondaryIndexes": [
    {
      "Projection": {
        "NonKeyAttributes": [ "myattribute" ]
        ...
      }
      ...
    },
    {
      "ProjectionType": "INCLUDE"
      ...
    },
  ]
  ...
}

The value argument to addOverride will not be processed or translated in any way. Pass raw JSON values in here with the correct capitalization for CloudFormation. If you pass CDK classes or structs, they will be rendered with lowercased key names, and CloudFormation will reject the template.

pathRequired
  • Type: string

The path of the property, you can use dot notation to override values in complex types.

Any intermediate keys will be created as needed.

valueRequired
  • Type: any

The value.

Could be primitive or complex.

addPropertyDeletionOverride 
public addPropertyDeletionOverride(propertyPath: string): void

Adds an override that deletes the value of a property from the resource definition.

propertyPathRequired
  • Type: string

The path to the property.

addPropertyOverride 
public addPropertyOverride(propertyPath: string, value: any): void

Adds an override to a resource property.

Syntactic sugar for addOverride("Properties.<...>", value).

propertyPathRequired
  • Type: string

The path of the property.

valueRequired
  • Type: any

The value.

applyRemovalPolicy 
public applyRemovalPolicy(policy?: RemovalPolicy, options?: RemovalPolicyOptions): void

Sets the deletion policy of the resource based on the removal policy specified.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN). In some cases, a snapshot can be taken of the resource prior to deletion (RemovalPolicy.SNAPSHOT). A list of resources that support this policy can be found in the following link:

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-attribute-deletionpolicy.html#aws-attribute-deletionpolicy-options

policyOptional
  • Type: aws-cdk-lib.RemovalPolicy
optionsOptional
  • Type: aws-cdk-lib.RemovalPolicyOptions
getAtt 
public getAtt(attributeName: string, typeHint?: ResolutionTypeHint): Reference

Returns a token for an runtime attribute of this resource.

Ideally, use generated attribute accessors (e.g. resource.arn), but this can be used for future compatibility in case there is no generated attribute.

attributeNameRequired
  • Type: string

The name of the attribute.

typeHintOptional
  • Type: aws-cdk-lib.ResolutionTypeHint
getMetadata 
public getMetadata(key: string): any

Retrieve a value value from the CloudFormation Resource Metadata.

[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/metadata-section-structure.html

Note that this is a different set of metadata from CDK node metadata; this metadata ends up in the stack template under the resource, whereas CDK node metadata ends up in the Cloud Assembly.](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/metadata-section-structure.html

Note that this is a different set of metadata from CDK node metadata; this metadata ends up in the stack template under the resource, whereas CDK node metadata ends up in the Cloud Assembly.)

keyRequired
  • Type: string
obtainDependencies 
public obtainDependencies(): (Stack | CfnResource)[]

Retrieves an array of resources this resource depends on.

This assembles dependencies on resources across stacks (including nested stacks) automatically.

obtainResourceDependencies 
public obtainResourceDependencies(): CfnResource[]

Get a shallow copy of dependencies between this resource and other resources in the same stack.

removeDependency 
public removeDependency(target: CfnResource): void

Indicates that this resource no longer depends on another resource.

This can be used for resources across stacks (including nested stacks) and the dependency will automatically be removed from the relevant scope.

targetRequired
  • Type: aws-cdk-lib.CfnResource
replaceDependency 
public replaceDependency(target: CfnResource, newTarget: CfnResource): void

Replaces one dependency with another.

targetRequired
  • Type: aws-cdk-lib.CfnResource

The dependency to replace.

newTargetRequired
  • Type: aws-cdk-lib.CfnResource

The new dependency to add.

inspect 
public inspect(inspector: TreeInspector): void

Examines the CloudFormation resource and discloses attributes.

inspectorRequired
  • Type: aws-cdk-lib.TreeInspector

tree inspector to collect and process attributes.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isCfnElement Returns true if a construct is a stack element (i.e. part of the synthesized cloudformation template).
isCfnResource Check whether the given construct is a CfnResource.
fromOrganizationId No description.
isConstruct 
import { CircleCiOidcProvider } from '@blimmer/cdk-circleci-oidc'

CircleCiOidcProvider.isConstruct(x: any)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.

isCfnElement 
import { CircleCiOidcProvider } from '@blimmer/cdk-circleci-oidc'

CircleCiOidcProvider.isCfnElement(x: any)

Returns true if a construct is a stack element (i.e. part of the synthesized cloudformation template).

Uses duck-typing instead of instanceof to allow stack elements from different versions of this library to be included in the same stack.

xRequired
  • Type: any
isCfnResource 
import { CircleCiOidcProvider } from '@blimmer/cdk-circleci-oidc'

CircleCiOidcProvider.isCfnResource(construct: IConstruct)

Check whether the given construct is a CfnResource.

constructRequired
  • Type: constructs.IConstruct
fromOrganizationId 
import { CircleCiOidcProvider } from '@blimmer/cdk-circleci-oidc'

CircleCiOidcProvider.fromOrganizationId(scope: Construct, organizationId: string)
scopeRequired
  • Type: constructs.Construct
organizationIdRequired
  • Type: string

Properties

Name Type Description
node constructs.Node The tree node.
creationStack string[] No description.
logicalId string The logical ID for this CloudFormation stack element.
stack aws-cdk-lib.Stack The stack in which this element is defined.
ref string Return a string that will be resolved to a CloudFormation { Ref } for this element.
cfnOptions aws-cdk-lib.ICfnResourceOptions Options for this resource, such as condition, update policy etc.
cfnResourceType string AWS resource type.
attrArn string Returns the Amazon Resource Name (ARN) for the specified AWS::IAM::OIDCProvider resource.
tags aws-cdk-lib.TagManager A list of tags that are attached to the specified IAM OIDC provider.
thumbprintList string[] A list of certificate thumbprints that are associated with the specified IAM OIDC provider resource object.
clientIdList string[] A list of client IDs (also known as audiences) that are associated with the specified IAM OIDC provider resource object.
url string The URL that the IAM OIDC provider resource object is associated with.
arn string No description.
organizationId string No description.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

creationStackRequired 
public readonly creationStack: string[];
  • Type: string[]
logicalIdRequired 
public readonly logicalId: string;
  • Type: string

The logical ID for this CloudFormation stack element.

The logical ID of the element is calculated from the path of the resource node in the construct tree.

To override this value, use overrideLogicalId(newLogicalId).

stackRequired 
public readonly stack: Stack;
  • Type: aws-cdk-lib.Stack

The stack in which this element is defined.

CfnElements must be defined within a stack scope (directly or indirectly).

refRequired 
public readonly ref: string;
  • Type: string

Return a string that will be resolved to a CloudFormation { Ref } for this element.

If, by any chance, the intrinsic reference of a resource is not a string, you could coerce it to an IResolvable through Lazy.any({ produce: resource.ref }).

cfnOptionsRequired 
public readonly cfnOptions: ICfnResourceOptions;
  • Type: aws-cdk-lib.ICfnResourceOptions

Options for this resource, such as condition, update policy etc.

cfnResourceTypeRequired 
public readonly cfnResourceType: string;
  • Type: string

AWS resource type.

attrArnRequired 
public readonly attrArn: string;
  • Type: string

Returns the Amazon Resource Name (ARN) for the specified AWS::IAM::OIDCProvider resource.

tagsRequired 
public readonly tags: TagManager;
  • Type: aws-cdk-lib.TagManager

A list of tags that are attached to the specified IAM OIDC provider.

The returned list of tags is sorted by tag key. For more information about tagging, see Tagging IAM resources in the IAM User Guide .

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-oidcprovider.html#cfn-iam-oidcprovider-tags

thumbprintListRequired 
public readonly thumbprintList: string[];
  • Type: string[]

A list of certificate thumbprints that are associated with the specified IAM OIDC provider resource object.

For more information, see CreateOpenIDConnectProvider .

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-oidcprovider.html#cfn-iam-oidcprovider-thumbprintlist

clientIdListOptional 
public readonly clientIdList: string[];
  • Type: string[]

A list of client IDs (also known as audiences) that are associated with the specified IAM OIDC provider resource object.

For more information, see CreateOpenIDConnectProvider .

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-oidcprovider.html#cfn-iam-oidcprovider-clientidlist

urlOptional 
public readonly url: string;
  • Type: string

The URL that the IAM OIDC provider resource object is associated with.

For more information, see CreateOpenIDConnectProvider .

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-oidcprovider.html#cfn-iam-oidcprovider-url

arnRequired 
public readonly arn: string;
  • Type: string
organizationIdRequired 
public readonly organizationId: string;
  • Type: string

Constants

Name Type Description
CFN_RESOURCE_TYPE_NAME string The CloudFormation resource type name for this resource class.
CFN_RESOURCE_TYPE_NAMERequired 
public readonly CFN_RESOURCE_TYPE_NAME: string;
  • Type: string

The CloudFormation resource type name for this resource class.

CircleCiOidcRole

Define an IAM Role that can be assumed by a CircleCI Job via the CircleCI OpenID Connect Identity Provider.

Initializers 

import { CircleCiOidcRole } from '@blimmer/cdk-circleci-oidc'

new CircleCiOidcRole(scope: Construct, id: string, props: CircleCiOidcRoleProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props CircleCiOidcRoleProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
with Applies one or more mixins to this construct.
applyRemovalPolicy Apply the given removal policy to this resource.
addManagedPolicy Attaches a managed policy to this role.
addToPolicy Add to the policy of this principal.
addToPrincipalPolicy Adds a permission to the role's default policy document.
attachInlinePolicy Attaches a policy to this role.
grant Grant the actions defined in actions to the identity Principal on this resource.
grantAssumeRole Grant permissions to the given principal to assume this role.
grantPassRole Grant permissions to the given principal to pass this role.
withoutPolicyUpdates Return a copy of this Role object whose Policies will not be updated.
toString 
public toString(): string

Returns a string representation of this construct.

with 
public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

Mixins are applied in order. The list of constructs is captured at the start of the call, so constructs added by a mixin will not be visited. Use multiple with() calls if subsequent mixins should apply to added constructs.

mixinsRequired
  • Type: ...constructs.IMixin[]

The mixins to apply.

applyRemovalPolicy 
public applyRemovalPolicy(policy: RemovalPolicy): void

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

policyRequired
  • Type: aws-cdk-lib.RemovalPolicy
addManagedPolicy 
public addManagedPolicy(policy: IManagedPolicy): void

Attaches a managed policy to this role.

policyRequired
  • Type: aws-cdk-lib.aws_iam.IManagedPolicy

The the managed policy to attach.

addToPolicy 
public addToPolicy(statement: PolicyStatement): boolean

Add to the policy of this principal.

statementRequired
  • Type: aws-cdk-lib.aws_iam.PolicyStatement
addToPrincipalPolicy 
public addToPrincipalPolicy(statement: PolicyStatement): AddToPrincipalPolicyResult

Adds a permission to the role's default policy document.

If there is no default policy attached to this role, it will be created.

statementRequired
  • Type: aws-cdk-lib.aws_iam.PolicyStatement

The permission statement to add to the policy document.

attachInlinePolicy 
public attachInlinePolicy(policy: Policy): void

Attaches a policy to this role.

policyRequired
  • Type: aws-cdk-lib.aws_iam.Policy

The policy to attach.

grant 
public grant(grantee: IPrincipal, actions: ...string[]): Grant

Grant the actions defined in actions to the identity Principal on this resource.

granteeRequired
  • Type: aws-cdk-lib.aws_iam.IPrincipal
actionsRequired
  • Type: ...string[]
grantAssumeRole 
public grantAssumeRole(identity: IPrincipal): Grant

Grant permissions to the given principal to assume this role.

identityRequired
  • Type: aws-cdk-lib.aws_iam.IPrincipal
grantPassRole 
public grantPassRole(identity: IPrincipal): Grant

Grant permissions to the given principal to pass this role.

identityRequired
  • Type: aws-cdk-lib.aws_iam.IPrincipal
withoutPolicyUpdates 
public withoutPolicyUpdates(options?: WithoutPolicyUpdatesOptions): IRole

Return a copy of this Role object whose Policies will not be updated.

Use the object returned by this method if you want this Role to be used by a construct without it automatically updating the Role's Policies.

If you do, you are responsible for adding the correct statements to the Role's policies yourself.

optionsOptional
  • Type: aws-cdk-lib.aws_iam.WithoutPolicyUpdatesOptions

Static Functions

Name Description
isConstruct Checks if x is a construct.
isOwnedResource Returns true if the construct was created by CDK, and false otherwise.
isResource Check whether the given construct is a Resource.
customizeRoles Customize the creation of IAM roles within the given scope.
fromRoleArn Import an external role by ARN.
fromRoleName Import an external role by name.
isRole Return whether the given object is a Role.
isConstruct 
import { CircleCiOidcRole } from '@blimmer/cdk-circleci-oidc'

CircleCiOidcRole.isConstruct(x: any)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.

isOwnedResource 
import { CircleCiOidcRole } from '@blimmer/cdk-circleci-oidc'

CircleCiOidcRole.isOwnedResource(construct: IConstruct)

Returns true if the construct was created by CDK, and false otherwise.

constructRequired
  • Type: constructs.IConstruct
isResource 
import { CircleCiOidcRole } from '@blimmer/cdk-circleci-oidc'

CircleCiOidcRole.isResource(construct: IConstruct)

Check whether the given construct is a Resource.

constructRequired
  • Type: constructs.IConstruct
customizeRoles 
import { CircleCiOidcRole } from '@blimmer/cdk-circleci-oidc'

CircleCiOidcRole.customizeRoles(scope: Construct, options?: CustomizeRolesOptions)

Customize the creation of IAM roles within the given scope.

It is recommended that you do not use this method and instead allow CDK to manage role creation. This should only be used in environments where CDK applications are not allowed to created IAM roles.

This can be used to prevent the CDK application from creating roles within the given scope and instead replace the references to the roles with precreated role names. A report will be synthesized in the cloud assembly (i.e. cdk.out) that will contain the list of IAM roles that would have been created along with the IAM policy statements that the role should contain. This report can then be used to create the IAM roles outside of CDK and then the created role names can be provided in usePrecreatedRoles.

Example

declare const app: App;
Role.customizeRoles(app, {
  usePrecreatedRoles: {
    'ConstructPath/To/Role': 'my-precreated-role-name',
  },
});
scopeRequired
  • Type: constructs.Construct

construct scope to customize role creation.

optionsOptional
  • Type: aws-cdk-lib.aws_iam.CustomizeRolesOptions

options for configuring role creation.

fromRoleArn 
import { CircleCiOidcRole } from '@blimmer/cdk-circleci-oidc'

CircleCiOidcRole.fromRoleArn(scope: Construct, id: string, roleArn: string, options?: FromRoleArnOptions)

Import an external role by ARN.

If the imported Role ARN is a Token (such as a CfnParameter.valueAsString or a Fn.importValue()) and the referenced role has a path (like arn:...:role/AdminRoles/Alice), the roleName property will not resolve to the correct value. Instead it will resolve to the first path component. We unfortunately cannot express the correct calculation of the full path name as a CloudFormation expression. In this scenario the Role ARN should be supplied without the path in order to resolve the correct role resource.

scopeRequired
  • Type: constructs.Construct

construct scope.

idRequired
  • Type: string

construct id.

roleArnRequired
  • Type: string

the ARN of the role to import.

optionsOptional
  • Type: aws-cdk-lib.aws_iam.FromRoleArnOptions

allow customizing the behavior of the returned role.

fromRoleName 
import { CircleCiOidcRole } from '@blimmer/cdk-circleci-oidc'

CircleCiOidcRole.fromRoleName(scope: Construct, id: string, roleName: string, options?: FromRoleNameOptions)

Import an external role by name.

The imported role is assumed to exist in the same account as the account the scope's containing Stack is being deployed to.

scopeRequired
  • Type: constructs.Construct

construct scope.

idRequired
  • Type: string

construct id.

roleNameRequired
  • Type: string

the name of the role to import.

optionsOptional
  • Type: aws-cdk-lib.aws_iam.FromRoleNameOptions

allow customizing the behavior of the returned role.

isRole 
import { CircleCiOidcRole } from '@blimmer/cdk-circleci-oidc'

CircleCiOidcRole.isRole(x: any)

Return whether the given object is a Role.

xRequired
  • Type: any

Properties

Name Type Description
node constructs.Node The tree node.
env aws-cdk-lib.ResourceEnvironment The environment this resource belongs to.
stack aws-cdk-lib.Stack The stack in which this resource is defined.
assumeRoleAction string When this Principal is used in an AssumeRole policy, the action to use.
grantPrincipal aws-cdk-lib.aws_iam.IPrincipal The principal to grant permissions to.
policyFragment aws-cdk-lib.aws_iam.PrincipalPolicyFragment Returns the role.
roleArn string Returns the ARN of this role.
roleId string Returns the stable and unique string identifying the role.
roleName string Returns the name of the role.
assumeRolePolicy aws-cdk-lib.aws_iam.PolicyDocument The assume role policy document associated with this role.
permissionsBoundary aws-cdk-lib.aws_iam.IManagedPolicy Returns the permissions boundary attached to this role.
principalAccount string The AWS account ID of this principal.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

envRequired 
public readonly env: ResourceEnvironment;
  • Type: aws-cdk-lib.ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

stackRequired 
public readonly stack: Stack;
  • Type: aws-cdk-lib.Stack

The stack in which this resource is defined.

assumeRoleActionRequired 
public readonly assumeRoleAction: string;
  • Type: string

When this Principal is used in an AssumeRole policy, the action to use.

grantPrincipalRequired 
public readonly grantPrincipal: IPrincipal;
  • Type: aws-cdk-lib.aws_iam.IPrincipal

The principal to grant permissions to.

policyFragmentRequired 
public readonly policyFragment: PrincipalPolicyFragment;
  • Type: aws-cdk-lib.aws_iam.PrincipalPolicyFragment

Returns the role.

roleArnRequired 
public readonly roleArn: string;
  • Type: string

Returns the ARN of this role.

roleIdRequired 
public readonly roleId: string;
  • Type: string

Returns the stable and unique string identifying the role.

For example, AIDAJQABLZS4A3QDU576Q.

roleNameRequired 
public readonly roleName: string;
  • Type: string

Returns the name of the role.

assumeRolePolicyOptional 
public readonly assumeRolePolicy: PolicyDocument;
  • Type: aws-cdk-lib.aws_iam.PolicyDocument

The assume role policy document associated with this role.

permissionsBoundaryOptional 
public readonly permissionsBoundary: IManagedPolicy;
  • Type: aws-cdk-lib.aws_iam.IManagedPolicy

Returns the permissions boundary attached to this role.

principalAccountOptional 
public readonly principalAccount: string;
  • Type: string

The AWS account ID of this principal.

Can be undefined when the account is not known (for example, for service principals). Can be a Token - in that case, it's assumed to be AWS::AccountId.

Structs

CircleCiConfiguration

Initializer 

import { CircleCiConfiguration } from '@blimmer/cdk-circleci-oidc'

const circleCiConfiguration: CircleCiConfiguration = { ... }

Properties

Name Type Description
provider ICircleCiOidcProvider Reference to CircleCI OpenID Connect Provider configured in AWS IAM.
projectIds string[] Provide the UUID(s) of the CircleCI project(s) you want to be allowed to use this role.
providerRequired 
public readonly provider: ICircleCiOidcProvider;

Reference to CircleCI OpenID Connect Provider configured in AWS IAM.

Either pass an construct defined by new CircleCiOidcProvider or a retrieved reference from CircleCiOidcProvider.fromOrganizationId. There can be only one (per AWS Account).

projectIdsOptional 
public readonly projectIds: string[];
  • Type: string[]
  • Default: All CircleCI projects in the provider's organization

Provide the UUID(s) of the CircleCI project(s) you want to be allowed to use this role.

If you don't provide this value, the role will be allowed to be assumed by any CircleCI project in your organization. You can find a project's ID in the CircleCI dashboard UI under the "Project Settings" tab. It's usually in a UUID format.

CircleCiOidcProviderProps

Initializer 

import { CircleCiOidcProviderProps } from '@blimmer/cdk-circleci-oidc'

const circleCiOidcProviderProps: CircleCiOidcProviderProps = { ... }

Properties

Name Type Description
organizationId string The ID of your CircleCI organization.
thumbprints string[] The OIDC thumbprints used by the provider.
organizationIdRequired 
public readonly organizationId: string;
  • Type: string

The ID of your CircleCI organization.

This is typically in a UUID format. You can find this ID in the CircleCI dashboard UI under the "Organization Settings" tab.

thumbprintsOptional 
public readonly thumbprints: string[];
  • Type: string[]

The OIDC thumbprints used by the provider.

You should not need to provide this value unless CircleCI suddenly rotates their OIDC thumbprints (e.g., in response to a security incident).

If you do need to generate this thumbprint, you can follow the instructions here: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc_verify-thumbprint.html

CircleCiOidcRoleProps

Props that define the IAM Role that can be assumed by a CircleCI job via the CircleCI OpenID Connect Identity Provider.

Besides {@link CircleCiConfiguration}, you may pass in any {@link RoleProps} except assumedBy which will be defined by this construct.

Initializer 

import { CircleCiOidcRoleProps } from '@blimmer/cdk-circleci-oidc'

const circleCiOidcRoleProps: CircleCiOidcRoleProps = { ... }

Properties

Name Type Description
provider ICircleCiOidcProvider Reference to CircleCI OpenID Connect Provider configured in AWS IAM.
projectIds string[] Provide the UUID(s) of the CircleCI project(s) you want to be allowed to use this role.
description string A description of the role.
externalIds string[] List of IDs that the role assumer needs to provide one of when assuming this role.
inlinePolicies {[ key: string ]: aws-cdk-lib.aws_iam.PolicyDocument} A list of named policies to inline into this role.
managedPolicies aws-cdk-lib.aws_iam.IManagedPolicy[] A list of managed policies associated with this role.
maxSessionDuration aws-cdk-lib.Duration The maximum session duration that you want to set for the specified role.
path string The path associated with this role.
permissionsBoundary aws-cdk-lib.aws_iam.IManagedPolicy AWS supports permissions boundaries for IAM entities (users or roles).
roleName string A name for the IAM role.
providerRequired 
public readonly provider: ICircleCiOidcProvider;

Reference to CircleCI OpenID Connect Provider configured in AWS IAM.

Either pass an construct defined by new CircleCiOidcProvider or a retrieved reference from CircleCiOidcProvider.fromOrganizationId. There can be only one (per AWS Account).

projectIdsOptional 
public readonly projectIds: string[];
  • Type: string[]
  • Default: All CircleCI projects in the provider's organization

Provide the UUID(s) of the CircleCI project(s) you want to be allowed to use this role.

If you don't provide this value, the role will be allowed to be assumed by any CircleCI project in your organization. You can find a project's ID in the CircleCI dashboard UI under the "Project Settings" tab. It's usually in a UUID format.

descriptionOptional 
public readonly description: string;
  • Type: string
  • Default: No description.

A description of the role.

It can be up to 1000 characters long.

externalIdsOptional 
public readonly externalIds: string[];
  • Type: string[]
  • Default: No external ID required

List of IDs that the role assumer needs to provide one of when assuming this role.

If the configured and provided external IDs do not match, the AssumeRole operation will fail.

inlinePoliciesOptional 
public readonly inlinePolicies: {[ key: string ]: PolicyDocument};
  • Type: {[ key: string ]: aws-cdk-lib.aws_iam.PolicyDocument}
  • Default: No policy is inlined in the Role resource.

A list of named policies to inline into this role.

These policies will be created with the role, whereas those added by addToPolicy are added using a separate CloudFormation resource (allowing a way around circular dependencies that could otherwise be introduced).

managedPoliciesOptional 
public readonly managedPolicies: IManagedPolicy[];
  • Type: aws-cdk-lib.aws_iam.IManagedPolicy[]
  • Default: No managed policies.

A list of managed policies associated with this role.

You can add managed policies later using addManagedPolicy(ManagedPolicy.fromAwsManagedPolicyName(policyName)).

maxSessionDurationOptional 
public readonly maxSessionDuration: Duration;
  • Type: aws-cdk-lib.Duration
  • Default: Duration.hours(1)

The maximum session duration that you want to set for the specified role.

This setting can have a value from 1 hour (3600sec) to 12 (43200sec) hours.

Anyone who assumes the role from the AWS CLI or API can use the DurationSeconds API parameter or the duration-seconds CLI parameter to request a longer session. The MaxSessionDuration setting determines the maximum duration that can be requested using the DurationSeconds parameter.

If users don't specify a value for the DurationSeconds parameter, their security credentials are valid for one hour by default. This applies when you use the AssumeRole* API operations or the assume-role* CLI operations but does not apply when you use those operations to create a console URL.

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html

pathOptional 
public readonly path: string;
  • Type: string
  • Default: /

The path associated with this role.

For information about IAM paths, see Friendly Names and Paths in IAM User Guide.

permissionsBoundaryOptional 
public readonly permissionsBoundary: IManagedPolicy;
  • Type: aws-cdk-lib.aws_iam.IManagedPolicy
  • Default: No permissions boundary.

AWS supports permissions boundaries for IAM entities (users or roles).

A permissions boundary is an advanced feature for using a managed policy to set the maximum permissions that an identity-based policy can grant to an IAM entity. An entity's permissions boundary allows it to perform only the actions that are allowed by both its identity-based policies and its permissions boundaries.

https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html

roleNameOptional 
public readonly roleName: string;
  • Type: string
  • Default: AWS CloudFormation generates a unique physical ID and uses that ID for the role name.

A name for the IAM role.

For valid values, see the RoleName parameter for the CreateRole action in the IAM API Reference.

IMPORTANT: If you specify a name, you cannot perform updates that require replacement of this resource. You can perform updates that require no or some interruption. If you must replace the resource, specify a new name.

If you specify a name, you must specify the CAPABILITY_NAMED_IAM value to acknowledge your template's capabilities. For more information, see Acknowledging IAM Resources in AWS CloudFormation Templates.

RoleProps

RoleProps.

Initializer 

import { RoleProps } from '@blimmer/cdk-circleci-oidc'

const roleProps: RoleProps = { ... }

Properties

Name Type Description
description string A description of the role.
externalIds string[] List of IDs that the role assumer needs to provide one of when assuming this role.
inlinePolicies {[ key: string ]: aws-cdk-lib.aws_iam.PolicyDocument} A list of named policies to inline into this role.
managedPolicies aws-cdk-lib.aws_iam.IManagedPolicy[] A list of managed policies associated with this role.
maxSessionDuration aws-cdk-lib.Duration The maximum session duration that you want to set for the specified role.
path string The path associated with this role.
permissionsBoundary aws-cdk-lib.aws_iam.IManagedPolicy AWS supports permissions boundaries for IAM entities (users or roles).
roleName string A name for the IAM role.
descriptionOptional 
public readonly description: string;
  • Type: string
  • Default: No description.

A description of the role.

It can be up to 1000 characters long.

externalIdsOptional 
public readonly externalIds: string[];
  • Type: string[]
  • Default: No external ID required

List of IDs that the role assumer needs to provide one of when assuming this role.

If the configured and provided external IDs do not match, the AssumeRole operation will fail.

inlinePoliciesOptional 
public readonly inlinePolicies: {[ key: string ]: PolicyDocument};
  • Type: {[ key: string ]: aws-cdk-lib.aws_iam.PolicyDocument}
  • Default: No policy is inlined in the Role resource.

A list of named policies to inline into this role.

These policies will be created with the role, whereas those added by addToPolicy are added using a separate CloudFormation resource (allowing a way around circular dependencies that could otherwise be introduced).

managedPoliciesOptional 
public readonly managedPolicies: IManagedPolicy[];
  • Type: aws-cdk-lib.aws_iam.IManagedPolicy[]
  • Default: No managed policies.

A list of managed policies associated with this role.

You can add managed policies later using addManagedPolicy(ManagedPolicy.fromAwsManagedPolicyName(policyName)).

maxSessionDurationOptional 
public readonly maxSessionDuration: Duration;
  • Type: aws-cdk-lib.Duration
  • Default: Duration.hours(1)

The maximum session duration that you want to set for the specified role.

This setting can have a value from 1 hour (3600sec) to 12 (43200sec) hours.

Anyone who assumes the role from the AWS CLI or API can use the DurationSeconds API parameter or the duration-seconds CLI parameter to request a longer session. The MaxSessionDuration setting determines the maximum duration that can be requested using the DurationSeconds parameter.

If users don't specify a value for the DurationSeconds parameter, their security credentials are valid for one hour by default. This applies when you use the AssumeRole* API operations or the assume-role* CLI operations but does not apply when you use those operations to create a console URL.

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html

pathOptional 
public readonly path: string;
  • Type: string
  • Default: /

The path associated with this role.

For information about IAM paths, see Friendly Names and Paths in IAM User Guide.

permissionsBoundaryOptional 
public readonly permissionsBoundary: IManagedPolicy;
  • Type: aws-cdk-lib.aws_iam.IManagedPolicy
  • Default: No permissions boundary.

AWS supports permissions boundaries for IAM entities (users or roles).

A permissions boundary is an advanced feature for using a managed policy to set the maximum permissions that an identity-based policy can grant to an IAM entity. An entity's permissions boundary allows it to perform only the actions that are allowed by both its identity-based policies and its permissions boundaries.

https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html

roleNameOptional 
public readonly roleName: string;
  • Type: string
  • Default: AWS CloudFormation generates a unique physical ID and uses that ID for the role name.

A name for the IAM role.

For valid values, see the RoleName parameter for the CreateRole action in the IAM API Reference.

IMPORTANT: If you specify a name, you cannot perform updates that require replacement of this resource. You can perform updates that require no or some interruption. If you must replace the resource, specify a new name.

If you specify a name, you must specify the CAPABILITY_NAMED_IAM value to acknowledge your template's capabilities. For more information, see Acknowledging IAM Resources in AWS CloudFormation Templates.

Protocols

ICircleCiOidcProvider

Describes a CircleCI OpenID Connect Identity Provider for AWS IAM.

Properties

Name Type Description
arn string No description.
organizationId string No description.
arnRequired 
public readonly arn: string;
  • Type: string
organizationIdRequired 
public readonly organizationId: string;
  • Type: string