Package: c7n-org
c7n-org: Multi Account Custodian Execution% [comment]: # (         !!! IMPORTANT !!!                    )
% [comment]: # (This file is moved during document generation.)
% [comment]: # (Only edit the original document at ./tools/c7n_org/README.md)c7n-org is a tool to run Custodian against multiple AWS accounts,
Azure subscriptions, GCP projects, or OCI tenancies in parallel.Installationpipinstallc7n-orgc7n-org has 3 run modes:Usage:c7n-org[OPTIONS]COMMAND[ARGS]...custodianorganizationmulti-accountrunner.

Options:--helpShowthismessageandexit.

Commands:reportreportonanAWScrossaccountpolicyexecutionrunrunacustodianpolicyacrossaccounts(AWS,Azure,GCP,OCI)run-scriptrunascriptacrossAWSaccountsIn order to run c7n-org against multiple accounts, a config file must
first be created containing pertinent information about the accounts:Example AWS Config File:accounts:-account_id:'123123123123'name:account-1regions:-us-east-1-us-west-2role:arn:aws:iam::123123123123:role/CloudCustodianvars:charge_code:xyztags:-type:prod-division:some division-partition:us-scope:pci...Example Azure Config File:subscriptions:-name:Subscription-1subscription_id:a1b2c3d4-e5f6-g7h8i9...-name:Subscription-2subscription_id:1z2y3x4w-5v6u-7t8s9r...Example GCP Config File:projects:-name:app-devproject_id:app-203501tags:-label:env:dev-name:app-prodproject_id:app-1291tags:-label:env:devExample OCI Config File:tenancies:-name:dev-tenancyprofile:DEVTENANCYregions:-us-ashburn-1-us-phoenix-1vars:environment:devtags:-type:test...Config File GenerationWe also distribute scripts to generate the necessary config file in thescriptsfolder.Note:Currently these are distributed only via git. Perhttps://github.com/cloud-custodian/cloud-custodian/issues/2420, we'll
be looking to incorporate them into a new c7n-org subcommand.ForAWS, the scriptorgaccounts.pygenerates a config file
from the AWS Organizations API.pythonorgaccounts.py-faccounts.ymlForAzure, the scriptazuresubs.pygenerates a config file
from the Azure Resource Management API.Please see theAdditional Azure Instructionsfor initial setup and other important info.pythonazuresubs.py-fsubscriptions.ymlForGCP, the scriptgcpprojects.pygenerates a config file from
the GCP Resource Management API.pythongcpprojects.py-fprojects.ymlForOCI, the scriptocitenancies.pygenerates a config file
using OCI Configuration file and OCI Organizations API.Please refer to theAdditional OCI Instructionsfor additional information.pythonocitenancies.py-ftenancies.ymlRunning a Policy with c7n-orgTo run a policy, the following arguments must be passed in:-c|accounts|projects|subscriptions|tenanciesconfigfile
-s|outputdirectory
-u|policyFor example:c7n-orgrun-caccounts.yml-soutput-utest.yml--dryrunAfter running the above command, the following folder structure will be created:output
    |_ account-1
        |_ us-east-1
            |_ policy-name
                |_ resources.json
                |_ custodian-run.log
        |_ us-west-2
            |_ policy-name
                |_ resources.json
                |_ custodian-run.log
    |- account-2
...Usec7n-org reportto generate a csv report from the output directory.Selecting accounts, regions, policies for executionYou can filter the accounts to be run against by either passing the
account name or id via the-aflag, which can be specified multiple
times, or alternatively with comma separated values.Groups of accounts can also be selected for execution by specifying
the-ttag filter.  Account tags are specified in the config
file. Given the above accounts config file, you can specify all prod
accounts with-t type:prod. You can specify the-tflag multiple
times or use a comma separated list.You can specify which policies to use for execution by either
specifying-por selecting groups of policies via their tags with-l. Both options support being specified multiple times or using
comma separated values.By default in AWS, c7n-org will execute in parallel across regions.
The-rflag can be specified multiple times and defaults to(us-east-1, us-west-2).  A special value ofallwill execute across
all regions.Seec7n-org run --helpfor more information.Defining and using variablesEach account/subscription/project configuration in the config file can
also define a variables sectionvarsthat can be used in policies'
definitions and are interpolated at execution time. These are in
addition to the default runtime variables custodian provides likeaccount_id,now, andregion.Example of defining in c7n-org config file:accounts:-account_id:'123123123123'name:account-1role:arn:aws:iam::123123123123:role/CloudCustodianvars:charge_code:xyzExample of using in a policy file:policies:-name:ec2-check-tagresource:aws.ec2filters:-"tag:CostCenter":"{charge_code}"Another enhancement forc7n-org run-scriptis to support a few vars in the script arg.
The available vars areaccount,account_id,regionandoutput_dir.c7n-orgrun-script-s.-cmy-projects.ymlgcp_check_{region}.sh# orc7n-orgrun-script-s.-cmy-projects.ymluse_another_policy_result.sh{output_dir}Note:Variable interpolation is sensitive to proper quoting and spacing,
i.e.,{ charge_code }would be invalid due to the extra white space. Additionally,
yaml parsing can transform a value like{charge_code}to null, unless it's quoted
in strings like the above example. Values that do interpolation into other content
don't require quoting, i.e., "my_{charge_code}".Other commandsc7n-org also supports running arbitrary scripts against accounts via
the run-script command.  For AWS the standard AWS SDK credential
information is exported into the process environment before executing.
For Azure and GCP, only the environment variablesAZURE_SUBSCRIPTION_IDandPROJECT_IDare exported(in addition of
the system env variables).c7n-org also supports generating reports for a given policy execution
across accounts via thec7n-org reportsubcommand.Additional Azure InstructionsIf you're using an Azure Service Principal for executing c7n-org
you'll need to ensure that the principal has access to multiple
subscriptions.For instructions on creating a service principal and granting access
across subscriptions, visit theAzure authentication docs
page.Additional OCI InstructionsThe scriptocitenancies.pyaccepts an optional argument--add-child-tenancieswhich adds all the child tenancies associated with theDEFAULTprofile's tenancy
in the generated c7n-org configuration file. If the profile for child tenancy is not available in
the OCI configuration file, then either user can add the profile for the child tenancy to the
OCI configuration file and replace the<ADD_PROFILE>entry in the c7n-org configuration with the
corresponding profile name or the user can delete the child tenancy entry from the
c7n-org configuration file. For more info about config file, refer to thispage.If the user wants to query for the resources in the specific compartments in c7n-org, then the user
can pass the compartment OCID's to theoci_compartmentsunder thevarssection like below. If theoci_comparmentsis not passed undervars, then the resources will be fetched from the tenancy level.tenancies:-name:dev-tenancyprofile:DEVTENANCYregions:-us-ashburn-1-us-phoenix-1vars:oci_compartments:ocid1.test.oc1..<unique_ID>EXAMPLE-compartmentId-2-Value,ocid1.test.oc1..<unique_ID>EXAMPLE-compartmentId-3-Valueenvironment:dev-name:test-tenancyprofile:TESTTENANCYregions:-us-ashburn-1vars:environment:test