foremast.cfg / config.py¶

Purpose ¶

This configuration holds information necessary for running foremast such as auth tokens, URLs, whitelists etc

Example Configuration ¶

; foremast.cfg
[base]
domain = example.com
envs = dev,stage,prod
regions = us-east-1,us-west-2
ami_json_url = http://s3.bucketname.com/ami_lookup.json
git_url = https://git.example.com
gate_api_url = http://gate-api.example.com:8084
templates_path = ../../foremast-templates
default_run_as_user = trigger_runner
default_securitygroup_rules = { "bastion" : [ { "start_port": "22", "end_port": "22", "protocol": "tcp" } ],
                                "serviceapp" : [ { "start_port": "8080", "end_port": "8080", "protocol": "tcp" } ] }

[credentials]
gitlab_token = 123token23423343
slack_token = 123slack3203120312

[whitelists]
asg_whitelist = application1,application2

[formats]
app = {project}{repo}
dns_elb = lb-{project}{repo}.{env}.{domain}
s3_bucket = secret-{env}-{project}

[task_timeouts]
default = 120
envs = { "dev" : { "deleteScalingPolicy": 240} }

# config.py

CONFIG = {
    'base': {
        'domain': 'example.com',
        'envs': 'dev,stage,prod',
        'regions': 'us-east-1,us-west-2',
        'vpc_name': 'vpc',
        'ami_json_url': 'http://s3.bucketname.com/ami_lookup.json',
        'git_url': 'https://git.example.com',
        'gate_api_url': 'http://gate-api.example.com:8084',
        'templates_path': '../../foremast-templates',
        'default_run_as_user': 'trigger_runner',
        'default_securitygroup_rules': {
            'bastion': [{'start_port': '22', 'end_port': '22', 'protocol': 'tcp'}],
            'serviceapp': [{'start_port': '8080', 'end_port': '8080', 'protocol': 'tcp' }],
        },
    },
    'credentials': {
        'gitlab_token': '123token23423343',
        'slack_token': '123slack3203120312',
        'gate_authentication': {
            'google_iap': {
                'enabled': False,
                'oauth_client_id': 'leeroyjenkins.apps.googleusercontent.com',
                'sa_credentials_path': '/tmp/service-account-creds.json'
            }
        }
    },

    'whitelists': {
        'asg_whitelist': 'application1,application2',
    },
    'formats': {
        'app': '{project}{repo}',
        'dns_elb': 'lb-{project}{repo}.{env}.{domain}',
        's3_bucket': 'secret-{env}-{project}',
    },
    'timeouts': {
        'default': 120,
        'envs': { 'dev': { 'deleteScalingPolicy': 240 } },
    }
}

Configuration Locations ¶

Foremast will look in the following locations, in order, for the foremast.cfg or config.py config file.

./.foremast/foremast.cfg
~/.foremast/.foremast.cfg
/etc/foremast/foremast/cfg
./config.py

Specifying a Configuration file ¶

Optionally, it is possible to specify the location of a configuration file for Foremast to use by setting the FOREMAST_CONFIG_FILE environment variable. This is useful if you do not store your config file in one of the locations listed above, or if you need to toggle between multiple configuration files to support different configurations.

Example: A config file for two different Spinnaker Instances

# Generate pipeline for spinnaker1
FOREMAST_CONFIG_FILE=config-spinnaker1.py
foremast generate pipeline
# Generate pipeline for spinnaker2
FOREMAST_CONFIG_FILE=config-spinnaker2.py
foremast generate pipeline

Configuration Details ¶

`[base]`¶

Sections for base information such as urls and general configurations

`domain`¶

The base domain of your applications. Used for generating DNS

Required: Yes

`envs`¶

Comma delimited list of environments/applications that will be managed with Foremast for AWS. See section [gcp] for GCP Environments.

Example: dev,stage,prod

Required: Yes

`env_configs` Keys ¶

Nested dictionary of environment names along with environment features

Type: Object

Default: None

Example Configuration:

        {
            'env_configs': {
                "build": {
                    "enable_approval_skip": True
                },
                "data": {
                    "enable_approval_skip": False
                },
                "media": {
                    "enable_approval_skip": False
                },
                "stage": {
                    "enable_approval_skip": True
                },
                "prod": {
                    "enable_approval_skip": False
                },
                "prodp": {
                    "enable_approval_skip": False
                }
            }
        }

``enable_approval_skip``
^^^^^^^^^^^^^^^^^^^^^^^^

    Determines if approval skips are allowed in this environment. Allows admins to ultimately enforce
    deployment approvals in templates

    | *Type*: boolean
    | *Default*: ``False``

`aws_types`¶

Warning

aws_types replaced types beginning in Foremast 5.x when GCP support was added. It is recommended to migrate from the deprecated types configuration option to the new aws_types.

List of foremast managed Pipeline types to allow for AWS deployments

Type: str

Example: ec2,lambda

Default: ec2,lambda,s3,datapipeline,rolling

Required: No

`gcp_types`¶

List of foremast managed Pipeline types to allow for GCP deployments

Type: str

Example: cloudfunction

Default: cloudfunction

Required: No

`aws_manual_types`¶

Warning

aws_manual_types replaced manual_types beginning in Foremast 5.x when GCP support was added. It is recommended to migrate from the deprecated manual_types configuration option to the new aws_manual_types.

List of pipeline types that will trigger Foremast’s manual pipeline template feature. When Foremast Infrastructure features are used the pipeline types listed here will create AWS infrastructure. See advanced_manual_pipelines for more details on this feature.

Type: str

Example: manual,custom_pipeline_name

Default: manual

Required: No

`gcp_manual_types`¶

List of pipeline types that will trigger Foremast’s manual pipeline template feature. When Foremast Infrastructure features are used the pipeline types listed here will create GCP infrastructure. See advanced_manual_pipelines for more details on this feature.

Type: str

Example: gke,custom_pipeline_name

Default: ````

Required: No

`regions`¶

Comma delimiated list of AWS regions managed by Foremast

Example: us-east-1,us-west-2

Required: Yes

`ami_json_url`¶

FQDN of where to query for AMI ID look ups. See ami-lookup.json for more details

Required: No

`gitlab_url`¶

FQDN of gitlab. Will be used for handling API calls to Gitlab

Required: No

`gate_api_url`¶

FQDN Of your spinnaker Gate instance. This is where all API calls to Spinnaker will go

Required: Yes

`templates_path`¶

Path to custom templates directory. If provided, Foremast will first look in this directory for any templates. This can be an absolute path, or a path relative to where you where you are running the Foremast commands. See Pipeline Flow and Examples for more details on custom templates.

Required: No

`runway_base_path`¶

Base path to use when looking for custom runway directories. If provided, Foremast will first look for Foremast runway files in this directory. This is useful if you have a different folder or location to store pipeline configuration values.

Type: str

Default: runway

Required: No

`default_run_as_user`¶

Default user to run pipelines as. This is needed for leveraging service accounts in Fiat.

Type: str

Default: null

Required: No

`default_ec2_securitygroups`¶

Comma separated list or json of EC2 security groups to include for all deployments. If a comma separated list is given, the groups are applied to all environments. If a json is provide, it assigns groups only to the specified environment.

Required: No

Example: office,test_sg,example

Example (json): {"dev": ["sg1", "sg2"], "stage": ["sg3"]}

`default_elb_securitygroups`¶

Comma separated list or json of ELB security groups to include for all deployments. If a comma separated list is given, the groups are applied to all environments. If a json is provide, it assigns groups only to the specified environment.

Required: No

Example: test_sg,example_elb_sg

Example (json): {"dev": ["sg1", "sg2"], "stage": ["sg3"]}

`default_securitygroup_rules`¶

Security group rules that should be included by default for the application specific group. If $self is used as the security group name, it will self-reference to its own application name.

Required: No

Example: { "bastion" : [ { "start_port": "22", "end_port": "22", "protocol": "tcp" } ] }

`ec2_pipeline_types`¶

foremast.consts.EC2_PIPELINE_TYPES = ('ec2', 'rolling')

Comma separated list of Pipeline Types to treat as EC2 deployments.

This is useful when defining custom Pipeline Types. When Pipeline Type matches, EC2 specific data is used in deployment, such as Auto Scaling Groups and Availability Zones.

Default: ec2,rolling

Required: No

Example: ec2,infrastructure,propeller

`gate_client_cert`¶

If accessing Gate via x509 certificate authentication, this value provides the local path to the certificate. Only PEM certs are supported at this time (containing both the key and certificate in the PEM).

Required: No

Example: /var/certs/gate-cert.pem

`gate_ca_bundle`¶

If accessing Gate via x509 leveraging a custom certificate authority (such as acting as your own CA), this value provides the local path to the CA bundle. It is recommended to use an existing CA Bundle and append your CA certificate to it (https://certifi.io/en/latest/)

Required: No

Example: /var/certs/CA.pem

`[credentials]`¶

Section for handling credential configurations such as tokens, usernames, and passwords

`gitlab_token`¶

Gitlab token used for authentication in Foremast

Required: No

`slack_token`¶

Slack token used for authentication when sending Slack messages from Foremast

Required: No

`gate_authentication` Keys ¶

Credential Provider Object used to authenticate to Gate

Type: Object

Default: None

Example Configuration:

{
    'credentials': {
        'gate_authentication': {
            'google_iap': {
                'enabled': False,
                'oauth_client_id': 'some_id.apps.googleusercontent.com',
                'sa_credentials_path': '/tmp/google-service-account.json'
            },
            'github': {
                'token': '<GITHUB_TOKEN>'
            }
        }
    }
}

`google_iap` Keys ¶

We currently support in addition to x509, Google Identity Aware Proxy authentication.

Determines if this authentication method should be used or not.

Type: boolean

Default: False

oauth_client_id

Application Client ID using Identity Aware Proxy. Can be found in the Google Cloud Console

Type: string

Default: None

sa_credentials_path

Path to Google Cloud Service Account used to Authenticate to Identity Aware Proxy. Must be added to IAP in GCP console to grant permission.

Type: string

Default: None

`[whitelists]`¶

Sections for configuring whitelist info

`asg_whitelist`¶

Comma delimiated list of applications to whitelist from ASG rules

Required: No

`[formats]`¶

Section handling the naming convention of applications, elb, iam, s3 buckets and other services.

The most common sections are shown. The complete list of sections and defaults are defined by the underlying library foremast-utils.

Any of the possible variables below can be used as the value.

domain organization domain
env dev, qa, production, etc
project lowercase git group/organization
repo lowercase git project/repository
raw_project git group/organization
raw_repo git project/repository

`domain`¶

A string of your organization’s domain

Default: example.com

Required: No

`app`¶

A string of the format of your application

Default: {repo}{project}

Required: No

`dns_elb`¶

An FQDN of your application’s Elastic Load Balancer (ELB)

Default: {repo}.{project}.{env}.{domain}

Required: No

`s3_bucket`¶

An string of your base S3 bucket name

Default: archaius-{env}

Required: No

`jenkins_job_name`¶

An string of the format of the application’s jenkins job name

Default: {project}_{repo}

Required: No

`[task_timeouts]`¶

Section handling customization of task timeouts when communicating with Spinnaker. Timeouts can vary per environment and per task.

`default`¶

The default task timeout value

Default: 120

Required: No

`envs`¶

A json object keyed by environment name. Each value should be a json object keyed by task name. This section only applies to AWS environments.

Default: 120

Required: No

`[gcp]`¶

Section handling GCP infrastructure and authentication configuration options.

`envs`¶

A json object keyed by environment name. Each value should be a json object that defines the GCP environment’s structure. The property service_account_project defines which project is used by Foremast when creating service accounts. You should use different a service_account_project for each environment to ensure IAM permissions are not granted between environments. See the page GCP Credentials for more info on setting up GCP credentials for Foremast.

Default: None

Required: Yes

Example structure:

{
    'stage': {
        'organization': 'your-org.com',
        'service_account_project': 'project-id-for-creating-service-accounts-stage',
        'service_account_path': '/path/to/service/account/used/by/foremast-stage.json'
    },
    'prod': {
        'organization': 'your-org.com',
        'service_account_project': 'project-id-for-creating-service-accounts-prod',
        'service_account_path': '/path/to/service/account/used/by/foremast-prod.json'
    },
}