Documentation for Ploigos

What is Ploigos?

Ploigos is an opinionated workflow used to transform ideas into delivered software in a production environment. Ploigos can be divided into two major components: the Idea Delivery Workflow and the CI/CD Workflow.

The Idea Delivery Workflow is an abstract process workflow that defines a high level view of how an organization can best take ideas that solve business problems and implement the solution in a well defined procedure. This process focuses on the specific actions that need to take place without identifying specific tools for each step. Ploigos provides a general use Idea Delivery Workflow that can be further customized to fit specific projects as needed. A workflow first approach identifies the organizational behaviors and expected outcomes to define what quality is. The workflow codifies and enforces these to ensure all aspects of security, compliance, trust, and privacy are addressed.

The CI/CD Workflow is the implementation of the software development portion of the Idea Delivery Workflow. Ploigos creates a framework for a modular, extensible, and opinionated CD/CD pipeline. Modularity and extensibility are accomplished by defining one or more 'Steps' in the CD/CD workflow, and automating the Step by creating a StepImplementer. As part of fulfilling the opinionated aspect, Ploigos provides a number of predefined Steps, StepImplementers, and several CI/CD Workflows.

Ploigos defines a reference high level workflow that covers the process of taking the genesis of an idea, idea development, integration, and review. In this high level rendering of the Ploigos workflow, the majority of steps are Predefined Procedures. These procedures are placeholders for more complex sub workflows containing multiple Procedures, the details of which are defined in later sections. This simplification allows for a 'one slide' view of the workflow.

The CI/CD Process Workflow is broken down into 3 broad categories:

Each workflow type at minimum follows the process below and only differs in the specific steps in the Setup, Continuous Integration(CI), and Continuous Deployment(CD) stages.

References to the different workflows are defined in the ploigos-jenkins-library repository. This repository provides references examples of the Minimal, Typical, and Everything Workflow.

Once a Idea Delivery Workflow and CI/CD Process Workflow is established, then the next task is to determine all of the types of components needed to implement the workflow. This is done by ensuring each of the required tool categories in the table below are being tracked as an item that is either deployed or provided by a 3rd party.

Finally, choosing the actual component implementers (meaning the specific software tools or products) can be performed. This section has components that are dictated by the established Idea Delivery Workflow, CI/CD Process Workflow, and the tool categories. Some of the categories below may be optional depending on the workflow.

The most basic requirement for the deployment of the Ploigos CI/CD Workflow is an operational OCP 4.x cluster.

The following guide shows how to deploy the reference implementation of the Ploigos Standard Workflow into an OCP 4.x cluster with a simple quarkus application as a demo.

Ploigos is an opinionated software development and deployment workflow. The Typical CI/CD workflow, as the provided suggested workflow to implement, presents specific technology chosen based on industry popularity, feature set, open source involvement, and proficiency by contributing members of Ploigos. These considerations, and many more, may be evaluated by a particular organization when deciding on specific component implementer within the workflow.

Some other considerations that guide opinions established in this document are:

In the following example, it will be demonstrated how to fork the official ploigos-step-runner and ploigos-jenkins-library repositories to the Gitea server hosted as part of the CI/CD Workflow, and update the reference application to use the forked repositories.

Each groovy file is split into two primary sections: the WorkflowParams which contains variables for the workflow that can be set in the application Jenkinsfile, and the following section which defines the Jenkins pipeline

When creating new pipelines, ensure that it contains at least the following stages:

For the new workflow, identify which environments will have deployments (DEV/TEST/PROD) and ensure each environment has a stage('<ENV>') entry defined. Substages under the stage(Continuous Integration) definition can be customized to match the planned CI/CD Workflow.

Before removing the definition for a stage, take note of all variables that are being used. If these variables are not used anywhere else in the file, the variable declaration at the top of the file should be removed. While all variables should be examined, the following are the main variables to watch out for:

Replacing an existing step (e.g., changing the package step to use npm) vs. adding a new step (e.g., an organization specific compliance scan) are almost identical, the only difference being how the process is started:

To replace the step implementer for an existing step in the process, first locate that step’s configuration in the configuration files (config.yml and config-secrets.yml by default).

Be sure to use sops to edit the secrets file; do not attempt to modify the file directly.

Locate the existing configuration; in the example of changing the package step from Maven to NPM:

Step Implementer - Before

Replace the implementer with the new one:

Step Implementer - After

If adding a new step implementer, simply add the step name and implementer into the file. While it does not matter which order the stage is added, convention is to add this configuration where it would belong in the actual pipeline (e.g., deploy can be defined before build, but this severely reduces readability of the file).

Step Implementer - New

The implementer will automatically be picked up since the NpmPackage class is defined under the package folder in the Ploigos Step Runner module. If the implementation lives under a folder that does not match the step name, it can be referenced using the fully qualified class name (e.g., ploigos_step_runner.step_implementers.shared.NpmGeneric). Once the desired step implementer is defined, review that implement documentation to determine the possible configuration options. Review the various "Configuration Key" options:

If the default values are acceptable, and no additional configuration is required, there should be no config section for the implementer. Do not put sensitive information in config.yaml; this information should be encrypted using SOPS as part of config-secrets.yaml

Currently, Ploigos utilizes a helm chart to set up the Kubernetes resources required to run a pipeline, such as a ServiceAccount, with associated RoleBinding and ClusterRole. As before with the Jenkins Library, this step will involve copying from an existing template. In the case of the cloud resources, however, an entirely new repository is required. The repository to copy from is: ploigos-charts

The simplest way to create a new repository for these cloud resources is:

With this repository created and the root commit pushed, create a branch for defining the workflow – while not required, strongly consider using the pattern feature/<name> for the branch name. On this branch, make the following changes:

Common Changes

Workflow Resources Changes

Perform the following changes under the charts/<workflow-folder> directory:

Deployment Resources Changes

If this workflow contains deployment steps, perform the following changes under the charts/<deploy-folder> directory:

If there is only one target deployment environment, all of the values could be put in a single values file, but this is not recommended. Instead, separate values into whether or not they would be common or environment specific if there was a second environment; this makes it easier to grow the workflow later, and use it as a reference for other workflows. Once all of these changes are made: add and commit the changes, push them up to the repository, and open a merge request.

All of these changes could have been done as part of the initial root commit, but this information was omitted in order to simplify the written instructions. It is up to the implementer to determine if this should be one or two commits.

Sensitive information, such as passwords and private encryption keys, should always be encrypted at rest. This creates a challenge for automation processes, since the tools involved require a secure means to access required authentication credentials without user intervention.

The Ploigos workflow solves this problem using Mozilla SOPS, a powerful tool with a wide array of functionality for protecting secrets at rest. A full explanation of its inner workings and functionality can be reviewed in their documentation; this section aims to provide a high-level overview of only the SOPS functionality that Ploigos takes advantage of for encrypting sensitive information required for an automated pipeline run.

The encrypted file is then stored in version control. The reference architecture for the Ploigos ecosystem expects this file to reside in the folder cicd/ploigos-step-runner-config (relative to the repository root folder), though this can be modified by overriding the value for stepRunnerConfigDir. The CI/CD workflow tool decrypts the values in this file in order to gain access to authentication secrets (e.g., tokens, passwords, keys) for various tools used across the pipeline. This removes the need for user input and only authorized users are able to modify this file.

The keys from the configuration key/value pairs are unencrypted, which carries two benefits. First, anyone with access to the file can see what values are stored in the file, without gaining access to the values themselves. Also, it is possible to use version control tooling (e.g., git diff) to individually identify which values have been changed at any point in time.

This will open a text editor with a pre-generated YAML template. Fill in configuration values as required, then save and quit. SOPS will automatically encrypt the document. To see this in action, open the file through a standard text editor (i.e., not through SOPS) and note that the following are true:

If values were encrypted with an individual developer’s private key, then only that developer would be able to decrypt those values. Instead, a symmetric encryption key is generated for encrypting configuration values, and that key is then protected with the user’s PGP public key. This way, the key can be encrypted multiple times using different PGP keys, allowing the owner of those keys to also decrypt the key (and thus the configuration values in turn).

As a prerequisite to adding a public key to a SOPS-encrypted file, the user performing the operation must already have:

Once these prerequisites are met, add the new PGP key using its fingerprint:

To revoke a user’s permissions, use the same command as above, but replace --add-pgp with --rm-pgp.

Generating the Workflow Runner Key

TODO: discuss generating public/private keypair for pipeline

Just as various users’ keys are added to the SOPS-encrypted configuration to be able to decrypt these values, the CI/CD workflow runner tool also requires a PGP public/private keypair. A user will need to generate this keypair, but it should only live on their machine temporarily; once this process is complete, the private key must be deleted from the local machine. The public key should be distributed the same way that all the other user’s public keys are.

Adding Key to Helm Chart

There is a Helm chart that will be run later in this process in order to prepare a pipeline for a specific application; to prepare a Ploigos pipeline; see the Create the Cloud Resources section for additional information.

The private key that was generated for the workflow tool needs to be loaded into a SOPS-encrypted file within this helm chart. The default location for storing the private key is: <cloud-resources>/charts/reference-quarkus-mvn-workflow/secrets.yaml

This file should be a SOPS-encrypted file (using PGP public keys from all users who should have access to this file) with the following content, placing the PGP private key inline as appropriate:

Running this Helm chart requires human intervention, so only users’ PGP keys should be added here. Once the cloud resources Helm chart is run, the output will contain the name of the secret that was created to hold this PGP key (e.g., PGP Keys Secret: pgp-keys-ploigos-workflow-dms-child-support).

The value for pgpKeysSecretName should be overridden in the Jenkinsfile to reference this value. When the pipeline is run, this PGP private key will be injected into the pod and imported, in order to decrypt pipeline configuration values.

Note that this secret is protected so as to only be accessed by a ServiceAccount with specific permissions; the workflow runner pod must be run using the same permissions.

TODO

This document implements the Red Hat Modular Documentation system. Full details of this documentation style can be found HERE. In addition, the chosen format for all documentation within this repository is Asciidoc. An Asciidoc quick reference can be found HERE

In summary, this modular documentation is based around the concept of dividing documentation content around user stories. Once the user stories are identified, each story is then developed into an Assembly. Each Assembly is made up of one or more of the 3 Module types: