Armory Docs – Get Started with Pipelines-as-Code

Plugins: Enable Pipelines-as-Code in Armory Continuous Deployment

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

Before you begin

You are running Armory Continuous Deployment.
You manage your instance using the Armory Operator.

Pipelines-as-Code is a built-in feature of Armory CD. You only need to configure your repo, enable the Dinghy service, and apply your changes to use Pipelines-as-Code.

If you are running open source Spinnaker, see the Pipelines-as-Code landing page for installation paths based on whether you are using Halyard or the Spinnaker Operator.

Where to configure the service

If you are using the spinnaker-kustomize-patches repo, put your config in the armory/features/pipelines-as-code/features.yml file.

If you are using a single spinnakerservice.yml manifest, put your config in the spec.spinnakerConfig.config.armory.dinghy section.

apiVersion: spinnaker.armory.io/v1alpha2
kind: SpinnakerService
metadata:
 name: spinnaker
spec:
 spinnakerConfig:
 config:
 armory:
 dinghy:

Enable Pipelines-as-Code

The Dinghy service is already enabled in the armory/features/pipelines-as-code/features.yml file, so you only need to modify your Kustomization recipe. Add an entry for Pipelines-as-Code in the components section of your kustomization.yml file:

components:
 - core/base
 - core/persistence/in-cluster
 - targets/kubernetes/default
 - armory/features/pipelines-as-code/

Add enabled: true to your dinghy section.

spec:
 spinnakerConfig:
 config:
 armory:
 dinghy:
 enabled: true

Configure your repo

Before configuring your repos, ensure you have the following:

A personal access token that has read access to the repo where you store your dinghyfile and the repo where you store module files. You should create a Kubernetes Secret for your personal access token so you don’t store the token in plain text in your config file.
The organization where the app repos and templates reside; for example, if your repo is armory-io/dinghy-templates, your template-org is armory-io.
The name of the repo containing your modules; for example, if your repo is armory-io/dinghy-templates, your template-repo is dinghy-templates.

Add the following to your config file:

spec:
 spinnakerConfig:
 config:
 armory:
 dinghy:
 enabled: true
 templateOrg: <repo-org>
 templateRepo: <dinghy-templates-repo>
 githubToken: <abc>
 githubEndpoint: <https://api.github.com>

All fields are required.

templateOrg: VCS organization or namespace where application and template repositories are located
templateRepo: VCS repository where module templates are located
githubToken: GitHub token; This field supports “encrypted” field references; see Secrets for details.
githubEndpoint: (Default: https://api.github.com) GitHub API endpoint. Useful if you’re using GitHub Enterprise.

GitHub webhooks

Set up webhooks at the organization level for push events. You can do this by going to https://github.com/organizations/<your_org_here>/settings/hooks.

Set content-type to application/json.
Set the Payload URL to your Gate URL. Depending on whether you configured Gate to use its own DNS name or a path on the same DNS name as Deck, the URL follows one of the following formats:
- https://<your-gate-url>/webhooks/git/github if you have a separate DNS name or port for Gate
- https://<your-spinnaker-url>/api/v1/webhooks/git/github if you’re using a different path for Gate

If your Gate endpoint is protected by a firewall, you need to configure your firewall to allow inbound webhooks from GitHub’s IP addresses. You can find the IPs in this API response. Read more about GitHub’s IP addresses.

You can configure webhooks on multiple GitHub organizations or repositories to send events to Dinghy. Only a single repository from one organization can be the shared template repository in Dinghy. However, Dinghy can process pipelines from multiple GitHub organizations. You want to ensure the GitHub token configured for Dinghy has permission for all the organizations involved.

Pull request validations

When you make a GitHub pull request (PR) and there is a change in a dinghyfile, Pipelines-as-Code automatically performs a validation for that dinghyfile. It also updates the GitHub status accordingly. If the validation fails, you see an unsuccessful dinghy check.

Make PR validations mandatory to ensure users only merge working dinghyfiles.

Perform the following steps to configure mandatory PR validation:

Go to your GitHub repository.
Click on Settings > Branches.
In Branch protection rules, select Add rule.
Add master in Branch name pattern so that the rule gets enforced on the master branch. Note that if this is a new repository with no commits, the “dinghy” option does not appear. You must first create a dinghyfile in any branch.
Select Require status checks to pass before merging and make dinghy required. Select Include administrators as well so that all PRs get validated, regardless of user.

The following screenshot shows what your GitHub settings should resemble:

Bitbucket has both cloud and server offerings. See the Atlassian docs for more on the name change from Stash to Bitbucket Server. Consult your company’s Bitbucket support desk if you need help determining what flavor and version of Bitbucket you are using.

Add the following to your config file:

spec:
 spinnakerConfig:
 config:
 armory:
 dinghy:
 enabled: true
 templateOrg: <repo-org>
 templateRepo: <dinghy-templates-repo>
 stashUsername: <stash_user>
 stashToken: <abc>
 stashEndpoint: <https://my-endpoint>

All fields are required.

templateRepo: VCS repository where module templates are located
stashUsername: Stash username
stashToken: Stash token. This field supports “encrypted” field references; see Secrets for details.
stashEndpoint: Stash API endpoint. If you’re using Bitbucket Server, update the endpoint to include the api e.g. https://your-endpoint-here.com/rest/api/1.0

If you’re using Bitbucket Server, update the endpoint to include the api, e.g. --stash-endpoint https://your-endpoint-here.com/rest/api/1.0

You need to set up webhooks for each project that has the dinghyfile or module separately. Make the webhook POST to: https://spinnaker.your-company.com:8084/webhooks/git/bitbucket. If you’re using Stash <v3.11.6, you need to install the webhook plugin to be able to set up webhooks.

Add the following to your config file:

spec:
 spinnakerConfig:
 config:
 armory:
 dinghy:
 enabled: true
 templateOrg: <repo-org>
 templateRepo: <dinghy-templates-repo>
 gitlabToken: <abc>
 gitlabEndpoint: <https://my-endpoint>

All fields are required.

templateOrg: VCS organization or namespace where application and template repositories are located
templateRepo: VCS repository where module templates are located
gitlabToken: GitLab token. This field supports “encrypted” field references; see Secrets for details.
gitlabEndpoint: GitLab endpoint

Under Settings -> Integrations on your project page, point your webhooks to https://<your-gate-url>/webhooks/git/gitlab. Make sure the server your GitLab install is running on can connect to your Gate URL. Armory also needs to communicate with your GitLab installation. Ensure that connectivity works as well.

Deploy

Apply your updates.

kubectl apply -k <kustomization-directory-path>

kubectl -n spinnaker apply -f spinnakerservice.yml

What’s next

Configure Pipelines-as-Code Optional Features

Plugins: Install Pipelines-as-Code in Spinnaker (Spinnaker Operator)

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

Overview

In this guide, you use the Kustomize files in the spinnaker-kustomize-patches repo to deploy the service and install the plugin. You do need to update the contents of some files.

Compatibility

Spinnaker Version	Pipelines-as-Code Service Version	Pipelines-as-Code Plugin Version
1.30.x	2.30	0.0.5
1.28.x	2.28	0.0.5
1.27.x	2.27	0.0.5
1.26.x	2.26	0.0.5

Before you begin

You are running open source Spinnaker.
You manage your instance using the Spinnaker Operator and the spinnaker-kustomize-patches repo. If you are using Halyard, see Install Pipelines-as-Code in Spinnaker (Halyard).

Find the files

You can find the Pipelines-as-Code files in the spinnaker-kustomize-patches repo’s plugins/oss/pipelines-as-code directory.

kustomization.yml: Kustomize build file
deployment.yml: spin-dinghy Deployment manifest
dinghy.yml: service config
pac-plugin-config.yml: plugin config
service.yml: spin-dinghy Service manifest
spinnaker.yml: Spinnaker service mapping
versions directory: contains version-specific values that Kustomize inserts into the manifest during generation

The spinnaker-kustomize-patches/recipes directory contains the example kustomization-oss-pac.yml recipe. You can use that recipe or copy the entries to your recipe. This guide uses the kustomization-oss-pac.yml recipe for examples.

Configure the service

Set your Spinnaker version

Make sure the service version is compatible with your Spinnaker version.

You specify the version in the patchesStrategicMerge section of plugins/oss/pipelines-as-code/kustomization.yml. You can find supported versions in the plugins/oss/pipelines-as-code/versions directory. For example, if you are running Spinnaker 1.27.x, replace ./versions/v-1.28.yml with ./versions/v-1.27.yml.

patchesStrategicMerge:
 - ./pac-plugin-config.yml
 - ./versions/v-1.28.yml

Configure your repo

Important

Configure your repo in the plugins/oss/pipelines-as-code/dinghy.yml file.

Before configuring your repos, ensure you have the following:

A personal access token that has read access to the repo where you store your dinghyfile and the repo where you store module files. You should create a Kubernetes Secret for your personal access token so you don’t store the token in plain text in your config file.
The organization where the app repos and templates reside; for example, if your repo is armory-io/dinghy-templates, your template-org is armory-io.
The name of the repo containing your modules; for example, if your repo is armory-io/dinghy-templates, your template-repo is dinghy-templates.

Add the following to your dinghy.yml config:

templateOrg: <repo-org>
templateRepo: <dinghy-templates-repo>
githubToken: <abc>
githubEndpoint: <https://api.github.com>

All fields are required.

templateOrg: VCS organization or namespace where application and template repositories are located
templateRepo: VCS repository where module templates are located
githubToken: GitHub token; This field supports “encrypted” field references; see Secrets for details.
githubEndpoint: (Default: https://api.github.com) GitHub API endpoint. Useful if you’re using GitHub Enterprise.

GitHub webhooks

Set up webhooks at the organization level for push events. You can do this by going to https://github.com/organizations/<your_org_here>/settings/hooks.

Set content-type to application/json.
Set the Payload URL to your Gate URL. Depending on whether you configured Gate to use its own DNS name or a path on the same DNS name as Deck, the URL follows one of the following formats:
- https://<your-gate-url>/webhooks/git/github if you have a separate DNS name or port for Gate
- https://<your-spinnaker-url>/api/v1/webhooks/git/github if you’re using a different path for Gate

Pull request validations

Make PR validations mandatory to ensure users only merge working dinghyfiles.

Perform the following steps to configure mandatory PR validation:

Go to your GitHub repository.
Click on Settings > Branches.
In Branch protection rules, select Add rule.
Add master in Branch name pattern so that the rule gets enforced on the master branch. Note that if this is a new repository with no commits, the “dinghy” option does not appear. You must first create a dinghyfile in any branch.
Select Require status checks to pass before merging and make dinghy required. Select Include administrators as well so that all PRs get validated, regardless of user.

The following screenshot shows what your GitHub settings should resemble:

Add the following to your dinghy.yml config:

templateOrg: <repo-org>
templateRepo: <dinghy-templates-repo>
stashUsername: <stash_user>
stashToken: <abc>
stashEndpoint: <https://my-endpoint>

All fields are required.

templateRepo: VCS repository where module templates are located
stashUsername: Stash username
stashToken: Stash token. This field supports “encrypted” field references; see Secrets for details.
stashEndpoint: Stash API endpoint. If you’re using Bitbucket Server, update the endpoint to include the api e.g. https://your-endpoint-here.com/rest/api/1.0

If you’re using Bitbucket Server, update the endpoint to include the api, e.g. --stash-endpoint https://your-endpoint-here.com/rest/api/1.0

Add the following to your dinghy.yml config:

templateOrg: <repo-org>
templateRepo: <dinghy-templates-repo>
gitlabToken: <abc>
gitlabEndpoint: <https://my-endpoint>

All fields are required.

templateOrg: VCS organization or namespace where application and template repositories are located
templateRepo: VCS repository where module templates are located
gitlabToken: GitLab token. This field supports “encrypted” field references; see Secrets for details.
gitlabEndpoint: GitLab endpoint

Configure the plugin

In pac-plugin-config.yml, make sure the version number is compatible with your Spinnaker instance.

Show the manifest

#------------------------------------------------------------------------------
# Example configuration for enabling the Pipeline as a Code plugin
#------------------------------------------------------------------------------
apiVersion: spinnaker.armory.io/v1alpha2
kind: SpinnakerService
metadata:
 name: spinnaker
spec:
 spinnakerConfig:
 profiles:
 # Configs in the spinnaker profile get applied to all services
 spinnaker:
 spinnaker:
 extensibility:
 repositories:
 repository:
 enabled: true
 url: https://raw.githubusercontent.com/armory-plugins/pluginRepository/master/repositories.json
 gate:
 spinnaker:
 extensibility:
 plugins:
 Armory.PipelineAsACode:
 enabled: true
 version: 0.0.5
 echo:
 armorywebhooks:
 enabled: true
 forwarding:
 baseUrl: http://spin-dinghy:8081
 endpoint: v1/webhooks
 spinnaker:
 extensibility:
 plugins:
 Armory.PipelineAsACode:
 enabled: true
 version: 0.0.5

Deploy

This step deploys the Dinghy service and installs the plugin. If you want to see the generated manifest before you deploy, execute kubectl kustomize.

Apply the updates to your Kustomization file.

kubectl apply -k <kustomization-directory-path>

What’s next

Configure Pipelines-as-Code Optional Features

Plugins: Install Pipelines-as-Code in Spinnaker (Halyard)

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

Installation overview

Installing Pipelines-as-Code consists of these steps:

Configure Kubernetes permissions.
Configure the Pipelines-as-Code service.
Deploy the Pipelines-as-Code service in the same Kubernetes cluster as Spinnaker.
Install the plugin into Spinnaker.

Compatibility

Spinnaker Version	Pipelines-as-Code Service Version	Pipelines-as-Code Plugin Version
1.30.x	2.30	0.0.5
1.28.x	2.28	0.0.5
1.27.x	2.27	0.0.5
1.26.x	2.26	0.0.5

Before you begin

You are running open source Spinnaker.
You manage your instance using Halyard. If you are using the Spinnaker Operator, see Install Pipelines-as-Code in Spinnaker (Spinnaker Operator)
You have permissions to create ServiceAccount, ClusterRole, and ClusterRoleBinding objects in your cluster.

Warning

The examples in this guide are for a vanilla Spinnaker installation. You may need to adjust them for your environment.

Configure Kubernetes permissions

The following manifest creates a ServiceAccount, ClusterRole, and ClusterRoleBinding. Apply the manifest in your spinnaker namespace.

apiVersion: v1
kind: ServiceAccount
metadata:
 name: dinghy-sa
 namespace: spinnaker
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
 name: dinghy-cluster-role
rules:
- apiGroups:
 - extensions
 resources:
 - ingresses
 - ingresses/status
 verbs:
 - get
 - list
 - watch
 - create
 - update
 - patch
 - delete
- apiGroups:
 - networking.k8s.io
 resources:
 - ingresses
 - ingresses/status
 verbs:
 - get
 - list
 - watch
 - create
 - update
 - patch
 - delete
- apiGroups:
 - ""
 resources:
 - pods
 - endpoints
 verbs:
 - get
 - list
 - watch
 - create
 - update
 - patch
 - delete
- apiGroups:
 - ""
 resources:
 - services
 - services/finalizers
 - events
 - configmaps
 - secrets
 - namespaces
 - jobs
 verbs:
 - create
 - get
 - list
 - update
 - watch
 - patch
 - delete
- apiGroups:
 - batch
 resources:
 - jobs
 verbs:
 - create
 - get
 - list
 - update
 - watch
 - patch
- apiGroups:
 - apps
 - extensions
 resources:
 - deployments
 - deployments/finalizers
 - deployments/scale
 - daemonsets
 - replicasets
 - statefulsets
 verbs:
 - create
 - get
 - list
 - update
 - watch
 - patch
 - delete
- apiGroups:
 - monitoring.coreos.com
 resources:
 - servicemonitors
 verbs:
 - get
 - create
- apiGroups:
 - spinnaker.armory.io
 resources:
 - '*'
 - spinnakerservices
 verbs:
 - create
 - get
 - list
 - update
 - watch
 - patch
- apiGroups:
 - admissionregistration.k8s.io
 resources:
 - validatingwebhookconfigurations
 verbs:
 - '*'
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
 name: dinghy-cluster-role-binding
roleRef:
 apiGroup: rbac.authorization.k8s.io
 kind: ClusterRole
 name: dinghy-cluster-role
subjects:
- kind: ServiceAccount
 name: dinghy-sa
 namespace: spinnaker

Configure the service

Create a ConfigMap to contain your Dinghy service configuration. Be sure to check the spinnaker.yml entry in the data section to ensure the values match your Spinnaker installation.

apiVersion: v1
kind: ConfigMap
metadata:
 name: spin-dinghy-config
 namespace: spinnaker
data:
 dinghy.yml: |
 autoLockPipelines: false
 dinghyFilename: dinghyfile
 dinghyIgnoreRegexp2Enabled: false
 echo:
 baseURL: ${services.echo.baseUrl}
 enabled: true
 fiat:
 baseUrl: ${services.fiat.baseUrl}
 enabled: ${services.fiat.enabled}
 front50:
 baseUrl: ${services.front50.baseUrl}
 enabled: ${services.front50.enabled}
 orca:
 baseUrl: ${services.orca.baseUrl}
 enabled: ${services.orca.enabled}
 redis:
 baseUrl: ${services.redis.baseUrl}
 repositoryRawdataProcessing: false
 spectator:
 applicationName: ${spring.application.name}
 webEndpoint:
 enabled: false
 spinnaker:
 extensibility:
 plugins: {}
 plugins-root-path: /opt/dinghy/plugins
 repositories: {}
 strict-plugin-loading: false
 githubEndpoint: https://api.github.com
 githubToken: CHANGEME
 templateOrg: CHANGEME
 templateRepo: CHANGEME
 spinnaker.yml: |
 global.spinnaker.timezone: America/Los_Angeles
 services:
 clouddriver:
 baseUrl: http://spin-clouddriver:7002
 enabled: true
 host: 0.0.0.0
 port: 7002
 clouddriverCaching:
 baseUrl: http://spin-clouddriver-caching:7002
 enabled: false
 host: 0.0.0.0
 port: 7002
 clouddriverRo:
 baseUrl: http://spin-clouddriver-ro:7002
 enabled: false
 host: 0.0.0.0
 port: 7002
 clouddriverRoDeck:
 baseUrl: http://spin-clouddriver-ro-deck:7002
 enabled: false
 host: 0.0.0.0
 port: 7002
 clouddriverRw:
 baseUrl: http://spin-clouddriver-rw:7002
 enabled: false
 host: 0.0.0.0
 port: 7002
 deck:
 baseUrl: http://localhost:9000
 enabled: true
 host: 0.0.0.0
 port: 9000
 dinghy:
 baseUrl: http://spin-dinghy:8081
 enabled: true
 host: 0.0.0.0
 port: 8081
 echo:
 baseUrl: http://spin-echo:8089
 enabled: true
 host: 0.0.0.0
 port: 8089
 echoScheduler:
 baseUrl: http://spin-echo-scheduler:8089
 enabled: false
 host: 0.0.0.0
 port: 8089
 echoWorker:
 baseUrl: http://spin-echo-worker:8089
 enabled: false
 host: 0.0.0.0
 port: 8089
 fiat:
 baseUrl: http://spin-fiat:7003
 enabled: false
 host: 0.0.0.0
 port: 7003
 front50:
 baseUrl: http://spin-front50:8080
 enabled: true
 host: 0.0.0.0
 port: 8080
 gate:
 baseUrl: http://localhost:8084
 enabled: true
 host: 0.0.0.0
 port: 8084
 igor:
 baseUrl: http://spin-igor:8088
 enabled: false
 host: 0.0.0.0
 port: 8088
 kayenta:
 baseUrl: http://spin-kayenta:8090
 enabled: false
 host: 0.0.0.0
 port: 8090
 monitoringDaemon:
 baseUrl: http://spin-monitoring-daemon:8008
 enabled: false
 host: 0.0.0.0
 port: 8008
 orca:
 baseUrl: http://spin-orca:8083
 enabled: true
 host: 0.0.0.0
 port: 8083
 redis:
 baseUrl: redis://spin-redis:6379
 enabled: true
 host: 0.0.0.0
 port: 6379
 rosco:
 baseUrl: http://spin-rosco:8087
 enabled: true
 host: 0.0.0.0
 port: 8087
 terraformer:
 baseUrl: http://spin-terraformer:7088
 enabled: false
 host: 0.0.0.0
 port: 7088

Configure your repo

Before configuring your repos, ensure you have the following:

A personal access token that has read access to the repo where you store your dinghyfile and the repo where you store module files. You should create a Kubernetes Secret for your personal access token so you don’t store the token in plain text in your config file.
The organization where the app repos and templates reside; for example, if your repo is armory-io/dinghy-templates, your template-org is armory-io.
The name of the repo containing your modules; for example, if your repo is armory-io/dinghy-templates, your template-repo is dinghy-templates.

Add the following to your dinghy.yml config:

templateOrg: <repo-org>
templateRepo: <dinghy-templates-repo>
githubToken: <abc>
githubEndpoint: <https://api.github.com>

All fields are required.

templateOrg: VCS organization or namespace where application and template repositories are located
templateRepo: VCS repository where module templates are located
githubToken: GitHub token; This field supports “encrypted” field references; see Secrets for details.
githubEndpoint: (Default: https://api.github.com) GitHub API endpoint. Useful if you’re using GitHub Enterprise.

GitHub webhooks

Set up webhooks at the organization level for push events. You can do this by going to https://github.com/organizations/<your_org_here>/settings/hooks.

Set content-type to application/json.
Set the Payload URL to your Gate URL. Depending on whether you configured Gate to use its own DNS name or a path on the same DNS name as Deck, the URL follows one of the following formats:
- https://<your-gate-url>/webhooks/git/github if you have a separate DNS name or port for Gate
- https://<your-spinnaker-url>/api/v1/webhooks/git/github if you’re using a different path for Gate

Pull request validations

Make PR validations mandatory to ensure users only merge working dinghyfiles.

Perform the following steps to configure mandatory PR validation:

Go to your GitHub repository.
Click on Settings > Branches.
In Branch protection rules, select Add rule.
Add master in Branch name pattern so that the rule gets enforced on the master branch. Note that if this is a new repository with no commits, the “dinghy” option does not appear. You must first create a dinghyfile in any branch.
Select Require status checks to pass before merging and make dinghy required. Select Include administrators as well so that all PRs get validated, regardless of user.

The following screenshot shows what your GitHub settings should resemble:

Add the following to your dinghy.yml config:

templateOrg: <repo-org>
templateRepo: <dinghy-templates-repo>
stashUsername: <stash_user>
stashToken: <abc>
stashEndpoint: <https://my-endpoint>

All fields are required.

templateRepo: VCS repository where module templates are located
stashUsername: Stash username
stashToken: Stash token. This field supports “encrypted” field references; see Secrets for details.
stashEndpoint: Stash API endpoint. If you’re using Bitbucket Server, update the endpoint to include the api e.g. https://your-endpoint-here.com/rest/api/1.0

If you’re using Bitbucket Server, update the endpoint to include the api, e.g. --stash-endpoint https://your-endpoint-here.com/rest/api/1.0

Add the following to your dinghy.yml config:

templateOrg: <repo-org>
templateRepo: <dinghy-templates-repo>
gitlabToken: <abc>
gitlabEndpoint: <https://my-endpoint>

All fields are required.

templateOrg: VCS organization or namespace where application and template repositories are located
templateRepo: VCS repository where module templates are located
gitlabToken: GitLab token. This field supports “encrypted” field references; see Secrets for details.
gitlabEndpoint: GitLab endpoint

Deploy the service

Replace <version> with the Pipelines-as-Code service version compatible with your Spinnaker version.

apiVersion: v1
kind: Service
metadata:
 name: spin-dinghy
 labels:
 app: spin
 cluster: spin-dinghy
spec:
 selector:
 app: spin
 cluster: spin-dinghy
 type: ClusterIP
 ports:
 - protocol: TCP
 port: 8081
 targetPort: 8081
---
apiVersion: apps/v1
kind: Deployment
metadata:
 name: spin-dinghy
 annotations:
 moniker.spinnaker.io/application: '"spin"'
 moniker.spinnaker.io/cluster: '"dinghy"'
 labels:
 app: spin
 cluster: spin-dinghy
 app.kubernetes.io/name: dinghy
 app.kubernetes.io/managed-by: armory
 app.kubernetes.io/part-of: spinnaker
 app.kubernetes.io/version: <version>
spec:
 replicas: 1
 selector:
 matchLabels:
 app: spin
 cluster: spin-dinghy
 template:
 metadata:
 annotations: null
 labels:
 app: spin
 cluster: spin-dinghy
 app.kubernetes.io/name: dinghy
 app.kubernetes.io/managed-by: armory
 app.kubernetes.io/part-of: spinnaker
 app.kubernetes.io/version: <version>
 spec:
 containers:
 - name: dinghy
 image: docker.io/armory/dinghy
 ports:
 - containerPort: 8081
 startupProbe:
 httpGet:
 path: /health
 port: 8081
 failureThreshold: 3
 periodSeconds: 10
 successThreshold: 1
 timeoutSeconds: 1
 readinessProbe:
 exec:
 command:
 - wget
 - --no-check-certificate
 - --spider
 - -q
 - http://localhost:8081/health
 failureThreshold: 3
 initialDelaySeconds: 90
 periodSeconds: 10
 successThreshold: 1
 timeoutSeconds: 1
 volumeMounts:
 - name: spin-dinghy-config-file
 mountPath: /opt/spinnaker/config
 volumes:
 - name: spin-dinghy-config-file
 secret:
 secretName: spin-dinghy-config-file

Apply the ConfigMap and Deployment manifests in your spinnaker namespace.

Install the plugin

A note about installing plugins in Spinnaker

When Halyard adds a plugin to a Spinnaker installation, it adds the plugin repository information to all services, not just the ones the plugin is for. This means that when you restart Spinnaker, each service restarts, downloads the plugin, and checks if an extension exists for that service. Each service restarting is not ideal for large Spinnaker installations due to service restart times. Clouddriver can take an hour or more to restart if you have many accounts configured.

The Pipelines-as-Code plugin extends Gate and Echo. To avoid every Spinnaker service restarting and downloading the plugin, do not add the plugin using Halyard. Instead, follow the Local Config installation method, in which you configure the plugin in each extended service’s local profile.

The Pipelines-as-Code plugin extends Gate and Echo. You should create or update the extended service’s local profile in the same directory as the other Halyard configuration files. This is usually ~/.hal/default/profiles on the machine where Halyard is running.

Replace <version> with the plugin version that’s compatible with your Spinnaker instance.

Add the following to gate-local.yml:

spinnaker:
 extensibility:
 plugins:
 Armory.PipelinesAsCode:
 enabled: true
 version: <version>
 repositories:
 pipelinesAsCode:
 enabled: true
 url: https://raw.githubusercontent.com/armory-plugins/pluginRepository/master/repositories.json

Add the following to echo-local.yml:

armorywebhooks:
 enabled; true
 forwarding:
 baseUrl: http://spin-dinghy:8081
 endpoint: v1/webhooks
spinnaker:
 extensibility:
 plugins:
 Armory.PipelinesAsCode:
 enabled: true
 version: <version>
 repositories:
 pipelinesAsCode:
 enabled: true
 url: https://raw.githubusercontent.com/armory-plugins/pluginRepository/master/repositories.json

armorywebhooks config tells the service where to forward events it receives from the repo.

Save your files and apply your changes by running hal deploy apply.

What’s next

Configure Pipelines-as-Code Optional Features

Plugins: Configure Pipelines-as-Code Optional Features

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

Where to configure the Dinghy service

Spinnaker (Halyard): dinghy.yml section of your ConfigMap
Spinnaker (Spinnaker Operator): spinnaker-kustomize-patches/plugins/oss/pipelines-as-code/dinghy.yml
Armory CD: Either spinnaker-kustomize-patches/armory/features/pipelines-as-code/features.yml or spinnakerservice.yml

Auto lock pipelines - disable

Set autoLockPipelines: false to disable lock pipelines in the UI before overwriting changes.

Add the following to your dinghy.yml config:

autoLockPipelines: false

spec:
 spinnakerConfig:
 config:
 armory:
 dinghy:
 autoLockPipelines: false

Branches

Custom branches

Configuring a custom branch is required if you are using a repo that does not use master or main as the default branch, or you want to use a branch other than master or main.

By default, Dinghy uses the master branch in your repository and fallbacks to main if master doesn’t exist. If you wish to use a different branch in your repository, you can configure that using the repoConfig tag in your YAML configuration.

The repoConfig tag supports a collection of the following values:

branch - the name of the branch you wish to use
provider - the name of the provider. Pipelines-as-Code supports the following:
- github
- bitbucket-cloud
- bitbucket-server
repo - the name of the repository

Add the following to your dinghy.yml config:

repoConfig:
- branch: some_branch
 provider: bitbucket-server
 repo: my-bitbucket-repository
- branch: some_branch
 provider: github
 repo: my-github-repository

spec:
 spinnakerConfig:
 profiles:
 dinghy:
 repoConfig:
 - branch: some_branch
 provider: bitbucket-server
 repo: my-bitbucket-repository
 - branch: some_branch
 provider: github
 repo: my-github-repository

Multiple branches

Early Access

The information below is written for an Early Access feature. Contact us if you are interested in using this feature! Your feedback will help shape the development of this feature.

Do not use Early Access features for production environments.

Each branch in a repository must be explicitly configured in a separate repoConfig item. In the example below, Dinghy properly handles changes from two branches, branch_a and branch_b in repository-GitHub-repository. Add the following to your dinghy.yml profile config:

multipleBranchesEnabled: true
repoConfig:
- branch: branch_a
 provider: github
 repo: my-github-repository
- branch: branch_b
 provider: github
 repo: my-github-repository
- branch: some_branch
 provider: bitbucket-server
 repo: my-bitbucket-repository

spec:
 spinnakerConfig:
 config:
 armory:
 dinghy:
 multipleBranchesEnabled: true
 profiles:
 dinghy:
 repoConfig:
 - branch: some_branch
 provider: bitbucket-server
 repo: my-bitbucket-repository
 - branch: some_branch
 provider: github
 repo: my-github-repository

Custom dinghyfile name

This changes the name of the file that describes pipelines.

Add the following to your dinghy.yml config:

dinghyFilename: <your-filename>

spec:
 spinnakerConfig:
 config:
 armory:
 dinghy:
 dinghyFilename: <your-filename>

External persistent database

The Pipelines-as-Code service uses an in-cluster Redis instance to store relationships between pipeline templates and pipeline config files (.dinghyfile). You can, however, configure the service to use an external persistent database.

Configure Redis

Armory highly recommends that you use an external Redis instance for production use. If Redis becomes unavailable, you need to update your pipeline config files in order for the service to repopulate Redis with the relationships.

You can only configure Dinghy to use a password with the default Redis user.

Add the following to your dinghy.yml config:

redis:
 baseUrl: "redis://spin-redis:6379"
 password: "password"

spec:
 spinnakerConfig:
 profiles:
 dinghy:
 redis: "redis://spin-redis:6379"
 password: "<password>"

Configure MySQL

Early Access

The Pipelines-as-Code service can use MySQL to store relationships between pipeline templates and pipeline Dinghy files. Armory recommends an external MySQL instance for production use because it can provide more durability for Pipelines-as-Code. If MySQL becomes unavailable, you need to update your Dinghy files in order to repopulate MySQL with the relationships.

Configure the RDBMS driver exactly as described in Set up Clouddriver to use SQL - Database Setup. The MySQL database schema must be configured to with:

Default character set utfmb4
Default collate utf8mb4_unicode_ci

First make sure the schema exists in your database.

CREATE SCHEMA IF NOT EXISTS dinghy DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
 CREATE USER IF NOT EXISTS 'dinghy_service'@'%' IDENTIFIED BY '${SOME_PASSWORD_HERE}';
 CREATE USER IF NOT EXISTS 'dinghy_migrate'@'%' IDENTIFIED BY '${SOME_PASSWORD_HERE}';
 GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, EXECUTE, SHOW VIEW ON dinghy.* TO 'dinghy_service'@'%';
 GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, REFERENCES, INDEX, ALTER, LOCK TABLES, EXECUTE, SHOW VIEW ON dinghy.* TO dinghy_migrate@'%';

Next, configure Pipelines-as-Code to use your MySQL database.

Add the following to your dinghy.yml config:

sql:
 baseUrl: mysql:3306
 databaseName: dinghy
 enabled: true
 password: <password>
 user: <user>

spec:
 spinnakerConfig:
 profiles:
 dinghy:
 sql:
 baseUrl: mysql:3306
 databaseName: dinghy
 enabled: true
 password: password
 user: user

Migration from Redis to SQL

There is a migration strategy to move the relationships from Redis to SQL. In order to do that, you need to have the configuration from your Redis and add the configuration for MySQL as shown previously. When you do this and the pod starts, what happens is that the migration is done automatically by a job. To verify that the migration was done successfully, you can access your database and run the following query:

select * from executions;
select * from fileurls;
select * from fileurl_childs;

In the executions table, you should be able to see one record with the name REDIS_TO_SQL_MIGRATION.

In fileurls and fileurl_childs, you should be able to see the migration information with the Dinghyfiles, modules, and their relationships.

After Dinghy finishes the migration, it closes the Redis connection and works in full MySQL mode.

Fiat

If you have enabled Fiat, add the field fiatUser: <your-service-account> to your config. Note that the service account has to be in a group that has read/write access to the pipelines you are updating.

If you have app specific permissions configured, make sure you add the service account. For information on how to create a service account, see Creating service accounts.

Add the following to your dinghy.yml config:

fiatUser: <your-service-account>

spec:
 spinnakerConfig:
 config:
 armory:
 dinghy:
 fiatUser: <your-service-account>

Negative expressions support

The Regexp2 engine supports negative expressions, so you don’t need to define patterns for all files to be ignored. You can ignore everything other than required files. For example, in your project you have some project-specific files: file.js, file.ts, file.css. You also have files used by Dinghy: dinghyfile, minimum-wait.stage.module, maximum-wait.stage.module. If you enable dinghyIgnoreRegexp2Enabled, you can create your .dinghyfile with one of the following regular expressions:

file.(js|ts|css)
^(?!.(.stage.module)|(dinghyfile)).

Both of those regular expressions product the same result:

file.js -> ignored
file.ts -> ignored
file.css -> ignored
dinghyfile -> processed by Dinghy
minimum-wait.stage.module -> processed by Dinghy
maximum-wait.stage.module -> processed by Dinghy

Add dinghyIgnoreRegexp2Enabled: true if you want Dinghy to ignore everything other than required files.

Add the following to your dinghy.yml config:

dinghyIgnoreRegexp2Enabled: true

spec:
 spinnakerConfig:
 config:
 armory:
 dinghy:
 dinghyIgnoreRegexp2Enabled: true

Notifications

Slack notifications

If you configured Armory CD or Spinnaker to send Slack notifications for pipeline events, you can configure Pipelines-as-Code to send pipeline update results to Slack.

Add the following to your dinghy.yml config:

notifiers:
 enabled: true # Enable to allow any notifier type to occur
 slack:
 enabled: true # Whether or not Slack notifications are enabled for Dinghy events
 channel: <my-channel> # Slack channel where notifications will be sent to
 github:
 enabled: false # (Default: true) Whether or not github notifications are enabled for Dinghy events; once `spec.spinnakerConfig.profiles.dinghy.notifiers` are enabled, only enable this if you want both Slack and GitHub notifications at the same time

spec:
 spinnakerConfig:
 config:
 armory:
 dinghy:
 enabled: true
 notifiers:
 enabled: true # Enable to allow any notifier type to occur
 slack:
 enabled: true # Whether or not Slack notifications are enabled for dinghy events
 channel: my-channel # Slack channel where notifications will be sent to
 github:
 enabled: false # (Default: true) Whether or not github notifications are enabled for Dinghy events, once spec.spinnakerConfig.prifles.dinghy.notifiers are enabled. Only enable if you want both slack and github notifications at the same time

GitHub notifications

Dinghy can provide more robust information to GitHub about executed pipeline changes. This information appears as a comment in the PR.

Keep the following in mind when enabling GitHub notifications:

When using Armory CD versions below 2.26.2, GitHub notifications are not supported with custom endpoints and should be disabled due to a known issue. This issue has been resolved as of 2.26.2, Dinghy Change #447.
Enabling this functionality may lead to a large number of comments on a pull request if, for example, you update a module that is used by multiple pipelines. This can lead to the GitHub UI not loading or GitHub rate limiting cause of related API calls.

Add the following to your dinghy.yml config:

notifiers:
 enabled: true
 github:
 enabled: true # (Default: true) Whether or not github notifications are enabled for Dinghy events; once `notifiers` are enabled, only enable this if you want both Slack and GitHub notifications at the same time

spec:
 spinnakerConfig:
 profiles:
 dinghy:
 notifiers:
 enabled: true
 github:
 enabled: true # (Default: true) Whether or not github notifications are enabled for Dinghy events, once spec.spinnakerConfig.profles.dinghy.notifiers are enabled

Permissions check for a commit

The userWritePermissionsCheckEnabled feature, when enabled, verifies if the author of a commit that changed app parameters has sufficient WRITE permission for that app. You can specify a list of authors whose permissions are not valid. This option’s purpose is to skip permissions checks for bots and tools.

How this feature works

A webhook generated by commits pushed to a branch contains information about the commit author. Dinghy extracts the author’s email and fetches user roles for that email from Fiat. Given the roles, Dinghy fetches app permissions and compares the app’s WRITE roles with the roles of the author. If they match, Dinghy processes the webhook and applies changes from the commit to the app or pipelines. If permissions don’t match, Dinghy rejects the webhook since the author doesn’t have the required write permissions.

How to enable

This feature is disabled by default to prevent users from experiencing unexpected application behavior. You can enable the feature by setting userWritePermissionsCheckEnabled to true. When you omit userWritePermissionsCheckEnabled or set it to false, Dinghy does not check permissions.

To skip permissions checks for users such as bots or service accounts, set the value of ignoreUsersWritePermissions to the comma-delimited list of repo user email addresses.

When userWritePermissionsCheckEnabled is false or omitted, ignoreUsersWritePermissions has no effect.

Add the following to your dinghy.yml config:

userWritePermissionsCheckEnabled: true
ignoreUsersWritePermissions: “user1@example.com,user2@example.com”

spec:
 spinnakerConfig:
 config:
 armory:
 dinghy:
 userWritePermissionsCheckEnabled: true
 ignoreUsersWritePermissions: “user1@example.com,user2@example.com”

Template formats

Pipelines-as-Code supports two additional template formats in addition to the default JSON:

HCL
YAML

Selecting one of these parsers means that all of your templates must also be in that format.

Add the following to your dinghy.yml config:

parserFormat: <parser-format>

spec:
 spinnakerConfig:
 profiles:
 dinghy:
 parserFormat: <parser-format>

Replace <parser-format with one of the parsers:

json (Default)
yaml
hcl

What’s next

Use Pipelines-as-Code in Armory Continuous Deployment