Spinnaker – CI

Docs: AWS CodeBuild

Mon, 01 Jan 0001 00:00:00 +0000

Setting up AWS CodeBuild as a Continuous Integration (CI) system within Spinnaker allows you to:

trigger pipelines when an AWS CodeBuild build changes its phase or state
add an AWS CodeBuild stage to your pipeline

The AWS Codebuild stage requires Spinnaker 1.19 or later.

Prerequisites

AWS CodeBuild project

You need to have an AWS CodeBuild project. To create a project, follow the instructions on how to create a CodeBuild service role (AWS CLI) .

Next, run the following command (make sure you replace the service role with the one created and region of your own choice):

aws codebuild create-project \
  --name spinnaker-project \
  --source "type=GITHUB,location=https://github.com/aws-samples/aws-codebuild-samples.git" \
  --artifacts "type=NO_ARTIFACTS" \
  --environment "type=LINUX_CONTAINER,computeType=BUILD_GENERAL1_SMALL,image=aws/codebuild/standard:4.0" \
  --service-role <YOUR_SERVICE_ROLE> \
  --region <YOUR_AWS_REGION>

Note: The project created by the command above doesn’t produce artifacts since NO_ARTIFACTS is specified for artifacts type. To create a project that generates artifacts, follow the instructions in the AWS CodeBuild user guide .

For more information about how to create a project to meet your needs, see the use case based samples in the AWS CodeBuild documentation.

IAM Role

You need to have an IAM role that has the following permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "codebuild:StopBuild",
        "codebuild:ListProjects",
        "codebuild:StartBuild",
        "codebuild:BatchGetBuilds"
      ],
      "Resource": "*"
    }
  ]
}

This role has to trust the Spinnaker auth role so that the managing account can assume this role to call CodeBuild. You can edit your trust relationship to add the following policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": <Your Spinnaker Auth Role>
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Configure Spinnaker to work with AWS CodeBuild

Add the following to igor-local.yml to enable code build integration

codebuild:
  enabled: true
  accounts:
  - name: accountName
    accountId: 1234667890
    region: us-west-2
    assumeRole: role/CiBuild

Configure an AWS CodeBuild stage

To run an AWS CodeBuild build as part of a Spinnaker pipeline, perform the following steps:

Create a stage of type AWS CodeBuild.
Configure the stage by selecting the following:
- AWS CodeBuild account to use to run the build
- The project name from the dropdown list
(Optional) In the Source Configuration section, you can also do the following:

Select the source artifact to use as the build source. If not specified, the source configured in the project is used.
Specify the source version . of the build source. If not specified, the latest version is used.
Specify the buildspec file . If left blank, the buildspec configured in the project is used.
Select secondary build sources. If not specified, the secondary sources configured in the project is used.

(Optional) In the Environment Configuration section, you can specify the image tag or image digest that identifies the Docker image to use. If not specified, the image configured in the project is used. Note: As a prerequisite, follow this user guide to set up your registry credentials in the project configuration.
(Optional) In the Advanced Configuration section, you can specify environment variables to use in the build. Only environment variables in plain text are supported. Parameter Store / Secrets Manager environment variables can be configured in the project.
(Optional) In the Produces Artifacts section, you can supply any artifacts that you expect the build to create in order to make these artifacts available to downstream stages. AWS CodeBuild supports creating S3 artifacts in ZIP format, which will be converted to Spinnaker artifacts and injected into the pipeline on completion of the build.

While your build is running, the stage details provide the following information:

Current status of the build
ARN of the build
The link to view the build in the AWS CodeBuild Console
The link to view the build logs in AWS CloudWatch Logs
The link to view the build logs in S3

Configure your pipeline trigger (Optional)

Configure your pipeline to get triggered when an AWS CodeBuild build completes:

Follow these instructions to set up a notification rule for your project. To trigger the pipeline on completion of the build, select Succeeded and Failed in the Events that trigger notifications section under Build state.
Follow these instructions to create an Amazon Pub/Sub trigger. Keep the following guidelines in mind:

Skip the step to create SNS topic, as we will use the SNS topic created in step 1.
Create an SQS queue and subscribe the queue to the SNS topic.
Skip the step to create an S3 bucket, as the notification will be sent from CodeBuild instead of from S3.
Write the Echo configuration and set up the Amazon Pub/Sub trigger in the Spinnaker UI.

Start a build in CodeBuild. Your pipeline gets triggered when the build completes.

Docs: Fiat Permissions

Mon, 01 Jan 0001 00:00:00 +0000

Unless you have set fiat.legacyFallback to true (defaults to false) you will need to configure Igor CI services with Fiat READ and WRITE permissions.

Here is a Jenkins example:

jenkins:
  enabled: true
  masters:
  - name: <jenkins master name>
    address: http://<jenkins ip>/jenkins
    username: <jenkins admin user>
    password: <admin password>
    csrf: true
    permissions:
      READ:
      - foo
      - bar
      WRITE:
      - bar

In the example above, users with the foo or bar roles will be able to see the build master and use it as a trigger, and users with the bar role will additionally be able to trigger builds.

Users without these roles will not see the build master in Deck at all.

Docs: Google Cloud Build

Mon, 01 Jan 0001 00:00:00 +0000

Setting up Google Cloud Build as a Continuous Integration (CI) system within Spinnaker allows you to:

trigger pipelines when a GCB build completes
add a GCB stage to your pipeline

Prerequisites

GCP project

You need to have a Google Cloud Platform project with the Cloud Build API enabled. You can enable the API with the following gcloud command:

gcloud services enable cloudbuild.googleapis.com

Pub/sub subscription

Google Cloud Build sends Build Notifications when the state of your build changes. Spinnaker subscribes to these pub/sub messages so that it can…

track the status of builds it has initiated in a GCB stage
trigger pipelines based on build status changes

Create a Subscription object for the cloud-builds topic in your project:

    PROJECT_ID=
    SUBSCRIPTION_NAME=spinnaker-cloud-build

    gcloud pubsub subscriptions create $SUBSCRIPTION_NAME \
      --topic projects/$PROJECT_ID/topics/cloud-builds \
      --project $PROJECT_ID

Service account

Finally, you will need a service account that has both Cloud Build Editor and Pub/Sub Subscriber permissions. The commands below look for the service account key in a path/file defined in $SERVICE_ACCOUNT_KEY.

Configure Spinnaker to work with Google Cloud Build

Make sure that you have locking enabled on igor

This will allow you to run multiple igor pods while NOT triggering duplicate executions. Make sure you have the following entry in your igor-local.yml file:

locking:
  enabled: true

Enable pub/sub

Read through and enable pub/sub integration with google . This should cover setting up google to send notifications that spinnaker will consume.

Configure the spinnaker services

You’ll want to add the following to consume GCB messages:

User interface

Add the following to your deck settings-local.js file to enable the UI around pub/sub.

window.spinnakerSettings.feature.ci = true;

// add other trigger types to show as needed.
window.spinnakerSettings.triggerTypes = ["cron", "pubsub"]

For a more complete list of UI options, see the deck settings file

Event processing

In echo (the event system) add the following config to echo-local.yml will enable subscriptions to events.

gcb:
  enabled: true
  accounts:
  - name: accountName 
    project: projectID
    subscriptionName: subscriptionForGCBEvents
    jsonKey: ifNeeded

GCB invocation

In igor (the CI build handler) add the following to igor-local.yml

gcb:
  enabled: true
  accounts:
  - name: accountName
    project: projectID
    cloudBuildRegion: <optional>
    jsonKey: authCredsIfNeeded

You’ll note that the fields are similar to echo, but missing the subscription name. Each service is responsible for different purposes. Echo handles notifications FROM GCB, while igor handles requests to INVOKE GCB builds. Orca (the execution engine) will call igor to get a list of accounts and make requests to GCB.

Regional Cloud Build (Private Pools)

If you are using a private pool in a region other than us-central1, you need to configure the cloudBuildRegion for your GCB account. GCP uses regional endpoints for non-default private pools.

Add the regional configuration directly in your Igor profile (~/.hal/default/profiles/igor-local.yml):

gcb:
  enabled: true
  accounts:
    - name: dev
      project: my-project-id
      subscriptionName: spinnaker-cloud-build
    - name: dev-us-east1
      project: my-project-id
      cloudBuildRegion: us-east1
      subscriptionName: spinnaker-cloud-build-us-east1

Important: Each regional account requires its own Pub/Sub subscription to avoid race conditions between accounts when processing build notifications.

Configure your pipeline trigger

Configure your pipeline to be triggered by a completed GCB build:

In your Pipeline configuration, click the Configuration stage on the far left of the pipeline diagram.
Click Automated Triggers.
In the Type field, select Pub/Sub.
In the Pub/Sub System Type field, select google.
In the Subscription Name field, select your $ACCOUNT_NAME value.
In the Attribute Constraints field, enter status in the Key, and SUCCESS (all upper case) in the Value field.
In the Payload Constraints field, you can enter any of the top-level fields from the Build object documentation as the key, and a Java regular expression as the value.
In the Expected Artifacts field, you can add any build artifacts as expected artifacts. For example, if the build produces a Docker image, you can add an expected artifact of type Docker with a value of gcr.io/my-project-id/my-application (replacing my-project-id and my-application with appropriate values). You can then use the produced image in downstream stages.

Configure a Google Cloud Build stage

To run a GCB build as part of a Spinnaker pipeline:

create a stage of type Google Cloud Build.
Configure the stage by selecting the GCB account to use to run the build, and entering the build configuration YAML in the provided text box: You may also provide the build definition YAML as an artifact.
In the Produces Artifacts section, you may supply any artifacts that you expect the build to create in order to make these artifacts available to downstream stages. Google Cloud Build supports creating either GCS or Docker image artifacts , either of which will be converted to Spinnaker artifacts and injected into the pipeline on completion of the build.

While your build is executing, the stage details will provide the current status of the build and a link to view the build logs in the Google Cloud Console:

Docs: Jenkins

Mon, 01 Jan 0001 00:00:00 +0000

Setting up Jenkins as a Continuous Integration (CI) system within Spinnaker lets you trigger pipelines with Jenkins, add a Jenkins stage to your pipeline, or add a Script stage to your pipeline.

Prerequisites

To connect Jenkins to Spinnaker, you need:

A running Jenkins Master at version 2.x, reachable at a URL ($BASEURL) from where Spinnaker runs.
A username/API key ($USERNAME/$APIKEY) pair able to authenticate against Jenkins using HTTP Basic Auth, if Jenkins is secured. A user’s API key can be found at $BASEURL/user/$USERNAME/configure.

Add your Jenkins master

Add the following to igor-local.yml to enable Jenkins;

jenkins:
  enabled: true
  masters:
    - name: my-jenkins-server
      address: https://my.jenkins.example.com/jenkins
      username: encrypted:secret
      csrf: false
      jsonPath: <OPTIONAL> when using google auth
      oauthScopes:
        - when using google auth
      token: encrypted:secret:ideally
      itemUpperThreshold: <OPTIONAL> maxItemsToProcessPerPollCycle
      trustStore: <OPTIONAL> whenUsingCustomCerts
      trustStoreType: <OPTIONAL> JKS or PKCS12
      trustStorePassword: <OPTIONAL> if needed, native is changeit
      keyStore: <OPTIONAL> If using MTLS
      keyStoreType: <OPTIONAL> PKCS12 or JKS
      keyStorePassword: <OPTIONAL>
      skipHostnameVerification: toSkipTLSValidation
      ciEnabled: defaultsTOFalse
      permissions:
        READ:
          - groupName
        WRITE:
          - groupName

It is recommended to use encrypted secrets for password information in the above

Note: If you use the GitHub OAuth plugin for authentication into Jenkins, you can use the GitHub $USERNAME, and use the OAuth token as the $APIKEY.

Configure Jenkins and Spinnaker for CSRF protection

To enable Spinnaker and Jenkins to share a crumb to protect against CSRF…

Configure Spinnaker to enable the csrf flag. Make sure the csrf value as mentioned above is set to true.

Here’s what your configuration looks like:

jenkins:
  enabled: true
  masters:
  - name: <jenkins master name>
    address: http://<jenkins ip>/pathIfNeeded
    username: <jenkins admin user>
    password: <admin password>
    csrf: true

Install Strict Crumb Issuer Plugin in Jenkins:

a. Under Manage Jenkins > Plugin Manager > Available, search for Strict Crumb Issuer Plugin, select Install
Enable CSRF protection in Jenkins:

a. Under Manage Jenkins > Configure Global Security, select Prevent Cross Site Request Forgery exploits.

b. Under Crumb Algorithm, select Strict Crumb Issuer.

c. Under Strict Crumb Issuer > Advanced, deselect Check the session ID

Enabling Backlinks from Jenkins to Spinnaker

You can configure orca such that it will update the description of a running Jenkins build and generate a suitable backlink.

Add the following to your orca-local.yml file the following:

spinnaker:
  baseUrl:
    www: https://spinnaker.ui.url

Jenkins backlinks will be generated as follows: This build was triggered by '<a href=...>{Pipeline Name}</a>' in Spinnaker.

Next steps

You can use Jenkins in your pipelines in one of three ways:

As a pipeline trigger
Using the built-in Jenkins stage
Using the Script stage

After you’ve completed the setup above, you’re ready to trigger pipelines with Jenkins or run the Jenkins stage. This is sufficient for most use cases. See Triggering Pipelines with Jenkins for more information.

Using the Script stage requires further configuration. See Configuring the Script Stage to finish setting it up.

Docs: Travis CI

Mon, 01 Jan 0001 00:00:00 +0000

You can configure Spinnaker to use Travis CI as your Continuous Integration system, trigger pipelines with Travis, or add a Travis stage to a pipeline.

Prerequisites

You need a Travis user with an API access token so that you get only the repos you should see.
That user needs adequate access in GitHub to trigger builds.

Add your Travis CI master

Enable Travis CI in igor-local.yml

travis:
  enabled: true
  masters:
  - name: someName
    baseUrl: https://travis-ci.com
    ## Address IS Required but MAY not be actually used anymore
    address: https://api.travis-ci.com
    githubToken: patUse
    numberOfJobs: number to poll for each cycle

It is recommended to use encrypted secrets for password information in the above

For more configuration options, see the travis configuration properties in igor.