Update Your AWS Connection

Update your AWS connection when CloudZero publishes new permission templates or when AWS changes its billing and cost management permissions. Keeping permissions up to date ensures CloudZero has access to the latest cost and resource data needed for accurate recommendations and new features. You control the permissions you grant CloudZero, and connections do not update themselves.

CloudZero publishes all IAM policies and CloudFormation templates as open source in the provision-account repository. The sections below use those published templates.

Automated connections

If you connected using the automated method, update the cloudzero-connected-account CloudFormation stack. Choose either the AWS Console or the AWS CLI.

Option A: AWS Console

1. Open the AWS CloudFormation console in the AWS account where the stack is deployed.
2. Find the cloudzero-connected-account stack. If you do not see it, uncheck View Nested and search for cloudzero.
3. Select Update.
4. Select Replace current template.
5. Paste the following URL into the Amazon S3 URL field:

https://cz-provision-account.s3.amazonaws.com/latest/services/connected_account.yaml

6. Select Next three times to reach the review page.
7. Check both boxes in the Capabilities section:
   • I acknowledge that AWS CloudFormation might create IAM resources with custom names.
   • I acknowledge that AWS CloudFormation might require the following capability: CAPABILITY_AUTO_EXPAND
8. Select Submit.

Option B: AWS CLI

The following command updates the stack while preserving your existing parameters. It requires the AWS CLI and the jq package.

aws cloudformation update-stack \
  --stack-name cloudzero-connected-account \
  --template-url https://cz-provision-account.s3.amazonaws.com/latest/services/connected_account.yaml \
  --parameters "$(aws cloudformation describe-stacks --stack-name cloudzero-connected-account | jq '.Stacks[0].Parameters')"

Manual connections

If you connected using the manual method, update the IAM role's trust policy and inline policy. Choose either the AWS Console or the AWS CLI.

Option A: AWS Console

1. Open the AWS IAM console in the AWS account where the role is deployed.
2. Search for cloudzero in the Roles list. Select the role with Trusted entities containing Account: 061190967865.
3. Update the trust policy:
   1. On the Trust relationships tab, select Edit trust policy.
   2. In the Principal section, ensure both CloudZero account IDs are listed. Keep your existing sts:ExternalId condition unchanged:

"Principal": {
  "AWS": [
    "arn:aws:iam::061190967865:root",
    "arn:aws:iam::559846027439:root"
  ]
}

3. Select Update policy.
4. Update the inline policy:
   1. On the Permissions tab, select the attached Customer inline policy.
   2. Select the JSON tab.
   3. Replace the policy content with the latest version for your account type:
      • Billing (Payer) account policy
      • Resources (Member) account policy
   4. Select Review policy, then Save changes.
5. Add the AWSBillingReadOnlyAccess managed policy:
   1. On the Permissions tab, select Add permissions and select Attach Policies.
   2. Search for AWSBillingReadOnlyAccess.
   3. Check the box next to the policy name.
   4. Select Add permissions.

Option B: AWS CLI

These commands require the AWS CLI and the jq package.

1. Find your role name, policy name, and External ID:

aws iam list-roles | jq -r -e '.Roles | map(select(.AssumeRolePolicyDocument.Statement[0].Principal.AWS == "arn:aws:iam::061190967865:root")) | map(.RoleName)[] | .'
aws iam list-role-policies --role-name <role-name> | jq -r -e '.PolicyNames[]'
aws iam get-role --role-name <role-name> | jq -r '.Role.AssumeRolePolicyDocument.Statement[0].Condition.StringEquals."sts:ExternalId"'

2. Replace <role-name>, <policy-name>, and <external-id> in the block below with the values from step 1. For <policy-url>, use the URL that matches your account type:
   • Billing (Payer): https://cz-provision-account.s3.amazonaws.com/latest/policies/master_payer.json
   • Resources (Member): https://cz-provision-account.s3.amazonaws.com/latest/policies/resource_owner.json

aws iam update-assume-role-policy \
  --role-name <role-name> \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": { "AWS": ["arn:aws:iam::061190967865:root", "arn:aws:iam::559846027439:root"] },
        "Action": "sts:AssumeRole",
        "Condition": { "StringEquals": { "sts:ExternalId": "<external-id>" } }
      }
    ]
  }'

aws iam put-role-policy \
  --role-name <role-name> \
  --policy-name <policy-name> \
  --policy-document "$(curl -XGET <policy-url>)"

aws iam attach-role-policy \
  --role-name <role-name> \
  --policy-arn arn:aws:iam::aws:policy/AWSBillingReadOnlyAccess

3. Copy and run the block above in your terminal.

What to expect

New permissions take effect once the changes are saved. No reconnection is needed in CloudZero. You can verify the connection health on the Connections page in Settings.

For details on what each permission grants, see AWS Permissions and Security.