Global Resources

Global Resources are defined in the top-level resource/ directory. They define cloud resources which do not belong to an environment or other logical grouping.

CloudTrail

The resource/cloudtrail.yaml file specifies CloudTrail resources.

AWS CloudTrail logs all AWS API activity. Monitor and react to changes in your AWS accounts with CloudTrail. A CloudTrail can be used to set-up a multi-account CloudTrail that sends logs from every account into a single S3 Bucket.

paco provision resource.cloudtrail
example resource/cloudtrail.yaml configuration
trails:
  mycloudtrail:
    enabled: true
    region: 'us-west-2'
    cloudwatchlogs_log_group:
      expire_events_after_days: '14'
      log_group_name: CloudTrail
    enable_log_file_validation: true
    include_global_service_events: true
    is_multi_region_trail: true
    enable_kms_encryption: true
    kms_users:
      - bob@example.com
      - paco.ref resource.iam.users.sallysmith
    s3_bucket_account: paco.ref accounts.security
    s3_key_prefix: cloudtrails
CloudTrail
Field name Type Purpose Constraints Default
accounts List<PacoReference> Accounts to enable this CloudTrail in. Leave blank to assume all accounts. Paco Reference to Account.  
cloudwatchlogs_log_group Object<CloudWatchLogGroup> CloudWatch Logs LogGroup to deliver this trail to.    
enable_kms_encryption Boolean Enable KMS Key encryption   False
enable_log_file_validation Boolean Enable log file validation   True
include_global_service_events Boolean Include global service events   True
is_multi_region_trail Boolean Is multi-region trail?   True
kms_users List<PacoReference> IAM Users with access to CloudTrail bucket Paco Reference to IAMUser. String Ok.  
region String Region to create the CloudTrail Must be a valid AWS Region name or empty string  
s3_bucket_account PacoReference Account which will contain the S3 Bucket where the CloudTrail is stored. Must be an paco.ref to an account Paco Reference to Account.  
s3_key_prefix String S3 Key Prefix specifies the Amazon S3 key prefix that comes after the name of the bucket. Do not include a leading or trailing / in your prefix. They are provided already.  

Base Schemas Resource, DNSEnablable, Deployable, Named, Title, Type

CodeCommit

The resource/codecommit.yaml file manages CodeCommit repositories and users. The top-level of the file is CodeCommitRepositoryGroups, and each group contains a set of CodeCommit Repositories.

Example resource/codecommit.yaml file
# Application CodeCommitRepositoryGroup
application:
  # SaaS API CodeCommitRepository
  saas-api:
    enabled: true
    account: paco.ref accounts.tools
    region: us-west-2
    description: "SaaS API"
    repository_name: "saas-api"
    users:
      bobsnail:
        username: bobsnail@example.com
        public_ssh_key: 'ssh-rsa AAAAB3Nza.........6OzEFxCbJ'

  # SaaS UI CodeCommitRepository
  saas-ui:
    enabled: true
    account: paco.ref accounts.tools
    region: us-west-2
    description: "Saas UI"
    repository_name: "saas-ui"
    users:
      bobsnail:
        username: bobsnail@example.com
        public_ssh_key: 'ssh-rsa AAAAB3Nza.........6OzEFxCbJ'
      external_dev_team:
        username: external_dev_team
        public_ssh_key: 'ssh-rsa AAZA5RNza.........6OzEGHb7'

# Docs CodeCommitRepositoryGroups
docs:
  saas-book:
    enabled: true
    account: paco.ref accounts.prod
    region: eu-central-1
    description: "The SaaS Book (PDF)"
    repository_name: "saas-book"
    users:
      bobsnail:
        username: bobsnail@example.com
        public_ssh_key: 'ssh-rsa AAAAB3Nza.........6OzEFxCbJ'

Provision CodeCommit repos and users with:

paco provision resource.codecommit

Be sure to save the AWS SSH key ID for each user after your provision their key. You can also see the SSH keys in the AWS Console in the IAM Users if you lose them.

Visit the CodeCommit service in the AWS Console to see the SSH Url for a Git repo.

To authenticate, if you are using your default public SSH key, you can embed the AWS SSH key ID as the user in SSH Url:

git clone ssh://APKAV........63ICK@server/project.git

Or add the AWS SSH key Id to your ~/.ssh/config file. This is the easiest way, especially if you have to deal with multiple SSH keys on your workstation:

Host git-codecommit.*.amazonaws.com
  User APKAV........63ICK
  IdentityFile ~/.ssh/my_pubilc_key_rsa

CodeCommit

Container for CodeCommitRepositoryGroup objects.

CodeCommit Container<CodeCommitRepositoryGroup>
Field name Type Purpose Constraints Default
         

Base Schemas Named, Title

CodeCommitRepositoryGroup

Container for CodeCommitRepository objects.

CodeCommitRepositoryGroup Container<CodeCommitRepository>
Field name Type Purpose Constraints Default
         

Base Schemas Named, Title

CodeCommitRepository

CodeCommit Repository

CodeCommitRepository
Field name Type Purpose Constraints Default
account PacoReference Account this repo belongs to. Paco Reference to Account.  
description String Repository Description    
external_resource Boolean Boolean indicating whether the CodeCommit repository already exists or not   False
region String AWS Region    
repository_name String Repository Name    
users Container<CodeCommitUser> CodeCommit Users    

Base Schemas Deployable, Named, Title

CodeCommitUser

CodeCommit User

CodeCommitUser
Field name Type Purpose Constraints Default
permissions Choice Permissions Must be one of ReadWrite or ReadOnly ReadWrite
public_ssh_key String CodeCommit User Public SSH Key    
username String CodeCommit Username    

Base Schemas Named, Title

EC2 Keypairs

The resource/ec2.yaml file manages AWS EC2 Keypairs.

paco provision resource.ec2.keypairs # all keypairs
paco provision resource.ec2.keypairs.devnet_usw2 # single keypair
Example resource/ec2.yaml file
keypairs:
  devnet_usw2:
    keypair_name: "dev-us-west-2"
    region: "us-west-2"
    account: paco.ref accounts.dev
  staging_cac1:
    keypair_name: "staging-us-west-2"
    region: "ca-central-1"
    account: paco.ref accounts.stage
  prod_usw2:
    keypair_name: "prod-us-west-2"
    region: "us-west-2"
    account: paco.ref accounts.prod

EC2KeyPair

EC2 SSH Key Pair

EC2KeyPair
Field name Type Purpose Constraints Default
account PacoReference AWS Account the key pair belongs to Paco Reference to Account.  
keypair_name String The name of the EC2 KeyPair    
region String AWS Region Must be a valid AWS Region name no-region-set

Base Schemas Named, Title

IAM

The resource/iam.yaml file contains IAM Users. Each user account can be given different levels of access a set of AWS accounts. For more information on how IAM Users can be managed, see Managing IAM Users with Paco.

paco provision resource.iam.users

IAMResource

IAM Resource contains IAM Users who can login and have different levels of access to the AWS Console and API.

IAMResource
Field name Type Purpose Constraints Default
users Container<IAMUsers> IAM Users    

Base Schemas Named, Title

IAMUsers

Container for IAMUser objects.

IAMUsers Container<IAMUser>
Field name Type Purpose Constraints Default
         

Base Schemas Named, Title

IAMUser

IAM User represents a user that will exist in one account, but can also have delegate IAM Roles in other accounts that they are allowed to assume.

example IAM User
enabled: true
account: paco.ref accounts.master
username: yourusername
description: 'Your Name - Paco Administrator'
console_access_enabled: true
programmatic_access:
  enabled: true
  access_key_1_version: 1
  access_key_2_version: 0
account_whitelist: all
permissions:
  administrator:
    type: Administrator
    accounts: all
  custom:
    accounts: dev
    managed_policies:
       - 'AWSDirectConnectReadOnlyAccess'
       - 'AmazonGlacierReadOnlyAccess'
    policies:
      - name: "AWS Polly full access"
        statement:
          - effect: Allow
            action:
              - 'polly:*'
            resource:
              - '*'
            condition:
              StringEquals:
                aws:username:
                  "yourusername"
IAMUser
Field name Type Purpose Constraints Default
account PacoReference Paco account reference to install this user Paco Reference to Account.  
account_whitelist CommaList Comma separated list of Paco AWS account names this user has access to    
console_access_enabled Boolean Console Access Boolean    
description String IAM User Description    
permissions Container<IAMUserPermissions> Paco IAM User Permissions    
programmatic_access Object<IAMUserProgrammaticAccess> Programmatic Access    
username String IAM Username    

Base Schemas Deployable, Named, Title

IAMUserProgrammaticAccess

IAM User Programmatic Access Configuration

IAMUserProgrammaticAccess
Field name Type Purpose Constraints Default
access_key_1_version Int Access key version id   0
access_key_2_version Int Access key version id   0

Base Schemas Enablable

IAMUserPermissions

Container for IAM User Permission objects.

IAMUserPermissions
Field name Type Purpose Constraints Default
         

Base Schemas Named, Title

BaseRole

BaseRole
Field name Type Purpose Constraints Default
assume_role_policy Object<AssumeRolePolicy> Assume role policy    
global_role_name Boolean Role name is globally unique and will not be hashed   False
instance_profile Boolean Instance profile   False
managed_policy_arns List<String> Managed policy ARNs    
max_session_duration Int Maximum session duration The maximum session duration (in seconds) 3600
path String Path   /
permissions_boundary String Permissions boundary ARN Must be valid ARN  
policies List<Policy> Policies    
role_name String Role name    

Base Schemas Named, Title

Role

IAM Role that is disabled by default

Role
Field name Type Purpose Constraints Default
         

Base Schemas BaseRole, Deployable, Named, Title

RoleDefaultEnabled

IAM Role that is enabled by default

RoleDefaultEnabled
Field name Type Purpose Constraints Default
         

Base Schemas BaseRole, Enablable, Named, Title

AssumeRolePolicy

AssumeRolePolicy
Field name Type Purpose Constraints Default
aws List<String> List of AWS Principals    
effect Choice Effect Must be one of ‘Allow’ or ‘Deny’  
service List<String> Service    

Policy

Policy
Field name Type Purpose Constraints Default
name String Policy name    
statement List<Statement> Statements    

Statement

Statement
Field name Type Purpose Constraints Default
action List<String> Action(s)    
condition Dict Condition Each Key is the Condition name and the Value must be a dictionary of request filters. e.g. { “StringEquals” : { “aws:username” : “johndoe” }} {}
effect Choice Effect Must be one of ‘Allow’ or ‘Deny’  
principal Object<Principal> Principal    
resource List<String> Resrource(s)    

Base Schemas Named, Title

Principal

Principal
Field name Type Purpose Constraints Default
aws List<String> List of AWS Principals    
service List<String> List of AWS Service Principals    

Base Schemas Named, Title

Route 53

Route53Resource

The resource/route53.yaml file manages AWS Route 53 hosted zones.

Provision Route 53 with:

paco provision resource.route53
Example resource/route53.yaml file
hosted_zones:
  example:
    enabled: true
    domain_name: example.com
    account: aim.ref accounts.prod
Route53Resource
Field name Type Purpose Constraints Default
hosted_zones Container<Route53HostedZone> Hosted Zones    

Base Schemas Named, Title

Route53HostedZone

Route53 Hosted Zone

Route53HostedZone
Field name Type Purpose Constraints Default
account PacoReference Account this Hosted Zone belongs to Paco Reference to Account.  
domain_name String Domain Name    
external_resource Object<Route53HostedZoneExternalResource> External HostedZone Id Configuration    
parent_zone String Parent Hozed Zone name    
private_hosted_zone Boolean Make this hosted zone private.   False
record_sets List<Route53RecordSet> List of Record Sets    
vpc_associations PacoReference The VPC the private hosted zone will be provisioned in. Paco Reference to VPC.  

Base Schemas Deployable, Named, Title

Route53HostedZoneExternalResource

Existing Hosted Zone configuration

Route53HostedZoneExternalResource
Field name Type Purpose Constraints Default
hosted_zone_id String ID of an existing Hosted Zone    
nameservers List<String> List of the Hosted Zones Nameservers    

Base Schemas Deployable, Named, Title

Route53RecordSet

Route53 Record Set

Route53RecordSet
Field name Type Purpose Constraints Default
record_name String Record Set Full Name    
resource_records List<String> Record Set Values    
ttl Int Record TTL   300
type String Record Set Type    

SNS Topics

The resource/snstopics.yaml file manages AWS Simple Notification Service (SNS) resources. SNS has only two resources: SNS Topics and SNS Subscriptions.

paco provision resource.snstopics
Example resource/snstopics.yaml file
account: paco.ref accounts.prod
regions:
  - 'us-west-2'
  - 'us-east-1'
groups:
  admin:
    title: "Administrator Group"
    enabled: true
    cross_account_access: true
    subscriptions:
      - endpoint: http://example.com/yes
        protocol: http
      - endpoint: https://example.com/orno
        protocol: https
      - endpoint: bob@example.com
        protocol: email
      - endpoint: bob@example.com
        protocol: email-json
      - endpoint: '555-555-5555'
        protocol: sms
      - endpoint: arn:aws:sqs:us-east-2:444455556666:queue1
        protocol: sqs
      - endpoint: arn:aws:sqs:us-east-2:444455556666:queue1
        protocol: application
      - endpoint: arn:aws:lambda:us-east-1:123456789012:function:my-function
        protocol: lambda