In general: org-formation init (or org-formation init-pipeline) needs to be ran in the context of the organization master account. The IAM account needs to be broadly provisioned (happy to specify what in more detail).
If you choose to pass a build-account-id option, you will need to have created this account on beforehand and run the org-formation command from within this account. Otherwise you will are expected to run the org-formation command in the master account.
Typing help after any command in the commandline will print documentation.
org-formationcli reference
Creates a local organization formation file that contains all organization resources. Running this command will create an S3 Bucket (hence the region) in your account that contains a state file which is used to track differences when updating your resources.
> org-formation init organization.yml --region us-east-1
note: at any time you should be able to delete the state bucket and start over using the init command above.
| option | default | description |
|---|---|---|
| --region | none | The --region used to create the S3 bucket used to store state |
| --cross-account-role-name | OrganizationAccountAccessRole |
Name of the cross account IAM Role that should be used for cross account access. |
Creates an organization as done using the init command as well as default CodeCommit, CodeBuild and CodePipeline resources. The initial commit will contain the organization file generated for your organization as well as a default tasks-file.
> org-formation init-pipeline --region us-east-1
note: at any time you should be able to run this command and start using the pipeline.
| option | default | description |
|---|---|---|
| --region | none | The --region used to create the AWS resources |
| --stack-name | organization-formation-build |
The name of the stack used to create the CodeCommit, CodeBuild and CodePipeline resources. |
| --resource-prefix | orgformation- |
A prefix used for the CodeBuild and CodePipeline resources. |
| --repository-name | organization-formation |
Name of the CodeCommit resource that will host the org-formation files. |
| --cross-account-role-name | OrganizationAccountAccessRole |
Name of the cross account IAM Role that should be used for cross account access. |
| --build-account-id | none | Account Id of an existing AWS Account within your organization that should be used to manage the organization. |
| --role-stack-name | organization-formation-role |
stack name used to create cross account roles for org-formation access. only used when --build-account-id is passed. |
| --exclude-accounts | none | comma delimited list of account ids that should be excluded |
note: if you specify --build-account-id when initializing org-formation, should must always pass the account id of the master account in any subsequent call. you can put this value in runtime configurations file.
Updates organizational resources specified in templateFile.
> org-formation update organization.yml
Creates a changeset that can be reviewed and later applied for changes in templateFile.
> org-formation create-change-set organization.yml
output will contain the changeset as well as the changeset name.
| option | default | description |
|---|---|---|
| --change-set-name | random value | Name of the changeset that can later be used to apply changes. |
Execute a changeset by name of changeSetName.
> org-formation execute-change-set change-set-name
Display a changeset by name of changeSetName.
> org-formation print-change-set change-set-name
Will deploy CloudFormation resources specified in templateFile.
> org-formation update-stacks template.yml --stack-name my-stack
| option | default | description |
|---|---|---|
| --stack-name | none | required The stack name used to deploy CloudFormation resources |
| --parameters | none | parameters that need to be passed to the CloudFormation template. |
| --termination-protection | false | If specified the stack will be created with termination protection. |
| --update-protection | false | When set to true will create a StackPolicy for the stacks that prevents any resource from being modified through CloudFormation. |
| --organization-file | undefined | path to the organization file that will be used to evaluate organizational bindings |
| --max-concurrent-stacks | 1 | Maximum number of stacks to be updated concurrently |
| --failed-stacks-tolerance | 0 | The number of failed stacks after which execution stops |
| --large-template-bucket-name | 0 | The name of the S3 bucket that should be used when uploading templates larger than 50_000 bytes |
parameters can be passed in a similar fashion CloudFormation parameters are passed:
> org-formation update-stacks template.yml --stack-name my-stack --parameters ParameterKey=Param1,ParameterValue=Val1 ParameterKey=Param2,ParameterValue=Val2
or the somewhat more simple fashion:
> org-formation update-stacks template.yml --stack-name my-stack --parameters Param1=Val1 Param2=Val2
Comma-delimited lists can be passed either by escaping the commas:
> org-formation update-stacks template.yml --stack-name my-stack --parameters ParameterKey=MyRegions,ParameterValue=eu-west-1\,us-east-2
or by using quotes (") around the parameter value:
> org-formation update-stacks template.yml --stack-name my-stack --parameters ParameterKey=MyRegions,ParameterValue="eu-west-1,us-east-2"
validates the CloudFormation templates that will be generated based on templateFile.
> org-formation validate-stacks template.yml --stack-name my-stack
| option | default | description |
|---|---|---|
| --stack-name | 'validation' | The stack name used to deploy CloudFormation resources (used in e.g. generated names for output) |
| --organization-file | undefined | path to the organization file that will be used to evaluate organizational bindings |
| --parameters | none | parameters that need to be passed to the CloudFormation template. |
| --large-template-bucket-name | 0 | The name of the S3 bucket that should be used when uploading templates larger than 50_000 bytes |
parameters can be passed in a similar fashion CloudFormation parameters are passed:
> org-formation validate-stacks template.yml --stack-name my-stack --parameters ParameterKey=Param1,ParameterValue=Val1 ParameterKey=Param2,ParameterValue=Val2
or the somewhat more simple fashion:
> org-formation validate-stacks template.yml --stack-name my-stack --parameters Param1=Val1 Param2=Val2
Will print out CloudFormation templates generated based on templateFile.
> org-formation update-stacks template.yml --stack-name my-stack
| option | default | description |
|---|---|---|
| --stack-name | 'print' | The stack name used to deploy CloudFormation resources (used in e.g. generated names for output) |
| --parameters | none | parameters that need to be passed to the CloudFormation template. |
| --organization-file | undefined | path to the organization file that will be used to evaluate organizational bindings |
| --no-print-parameters | print-parameters | do not print parameter values in parameter file |
| --large-template-bucket-name | 0 | The name of the S3 bucket that should be used when uploading templates larger than 50_000 bytes |
Lists all stacks deployed to accounts using org-formation
> org-formation describe-stacks
| option | default | description |
|---|---|---|
| --stackName | none | If specified will limit the output to changeset with specified stack name |
> org-formation execute-change-set change-set-name
Will delete all stacks of name my-stack that have been deployed using org-formation.
> org-formation delete-stacks --stack-name my-stack
| option | default | description |
|---|---|---|
| --max-concurrent-stacks | 1 | Maximum number of stacks to be deleted concurrently |
| --failed-stacks-tolerance | 0 | The number of failed stacks after which execution stops |
Note: Want to review the stacks that will be deleted? use
describe-stacks
Will perform tasks from tasksFile.
> org-formation perform-tasks tasks.yml
| option | default | description |
|---|---|---|
| --logical-name | 'default' | logical name of the tasks file, allows multiple taskfiles to be used together with --perform-cleanup action |
| --organization-file | undefined | path to the organization file that will be used to evaluate organizational bindings |
| --perform-cleanup | false | when set will cleanup resources created by previous perform-tasks after task is removed from tasks file |
| --parameters | none | parameter values that need to be used when processing the taskfile. |
| --max-concurrent-tasks | 1 | Maximum number of tasks to be executed concurrently |
| --failed-tasks-tolerance | 0 | The number of failed tasks after which execution stops |
| --max-concurrent-stacks | 1 | Maximum number of stacks (within a task) to be executed concurrently |
| --failed-stacks-tolerance | 0 | The number of failed stacks (within a task) after which execution stops |
| --large-template-bucket-name | 0 | The name of the S3 bucket that should be used when uploading templates larger than 50_000 bytes |
| --match | undefined | Matches a specific tasks using using a globPattern (e.g. --match 'MyTask/**') or the exact name of a task. |
| --dev | false | use development settings, e.g. DefaultDevelopmentBuildAccessRoleName instead of DefaultBuildAccessRoleName |
Parameters can be passed using the following syntax:
> org-formation perform-tasks taskfile.yml --parameters Param1=Val1 Param2=Val2
Will validate the tasks-file, including configured tasks.
> org-formation validate-tasks tasks.yml
| option | default | description |
|---|---|---|
| --organization-file | undefined | path to the organization file that will be used to evaluate organizational bindings |
Validation requires the following set of permissions:
PolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Action:
- s3:GetObject
Resource: '*' # you can specify the state bucket by arn
- Effect: Allow
Action:
- cloudformation:GetExports
- cloudformation:ListExports
- cloudformation:ValidateTemplate
Resource: '*'
- Effect: Allow
Action:
- sts:AssumeRole
Resource: 'arn:aws:iam::*:role/OrganizationAccountAccessRole' # you can restrict to certain accounts| option | default | description |
|---|---|---|
| --profile | none | The --profile option works just like the --profile option in the AWS cli. If no profile is specified it uses the default profile from your ~/.aws/config file |
| --state-bucket-name | organization-formation-${AWS::AccountId} |
The --state-bucket-name option allows you to specify which S3 Bucket state needs to be stored. The name may contain ${AWS::AccountId}. |
| --state-object | state.json |
The --state-object option allows you to specify which S3 object state needs to be stored in. |
| --no-color | the --no-color option will toggle off colorization of log files. |
|
| --print-stack | the --print-stack option will log stack traces for errors that occur. |
|
| --verbose | the --verbose option will log debug level information. |
|
| --master-account-id | the --master-account-id option must be specified when the org-formation command is ran from a non-master account |
|
| --exclude-accounts | none | comma delimited list of account ids that should be excluded |
The following options can be configured using a .org-formationrc file.
Values are ignored if passed as command line argument directly.
| option | description |
|---|---|
| profile | Will be used as default for --profile option |
| organizationFile | Will be used as default for --organization-file option |
| stateBucketName | Will be used as default for --state-bucket-name option |
| stateObject | Will be used as default for --state-object option |
| masterAccountId | Will be used as default for --master-account-id option |
example:
organizationFile = ./templates/organization.yml
stateBucketName = my-orgformation-production-bucket
profile = org-master