Skip to content

Commit 3e3ae3e

Browse files
mhdawsonmhdawson
authored
doc: initial version of ci/cd section (#143)
* doc: initial version of ci/cd section Signed-off-by: Michael Dawson <[email protected]>
1 parent c735764 commit 3e3ae3e

File tree

2 files changed

+163
-1
lines changed

2 files changed

+163
-1
lines changed

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ with only a subset of sections having recommendations):
7777
- [TypeScript](./docs/development/typescript.md)
7878
- [Accessibility](./docs/development/accessibility.md)
7979
- Cross origin resource sharing (CORS)
80-
- CI/CD
80+
- [CI/CD](./docs/development/ci-cd.md)
8181
- Npm
8282
- [Npm Proxy / Internal Registries](./docs/development/npm-proxy.md)
8383
- [Npm Publishing](./docs/development/npm-publishing.md)

‎docs/development/ci-cd.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
sidebar_position: 14
3+
---
4+
5+
# CI/CD
6+
7+
Based on common developer workflows as documented in the section titled
8+
[Typical Development Workflows](./dev-flows.md#typical-development-workflows)
9+
the end target/deployment artifact is often a container image. Most of our
10+
advice/recommendations are therefore in the context of building/testing
11+
one or more images.
12+
13+
In the context of a Node.js component the version of the component and
14+
the version of Node.js used to run that component are managed through
15+
a Dockerfile to configure the version of the component and the base
16+
image to be used in a deployment. The base image may be an
17+
existing Node.js image (for example)
18+
[ubi8/nodejs-16](https://catalog.redhat.com/software/containers/ubi8/nodejs-16/615aee9fc739c0a4123a87e1)
19+
image or a [dependency image](./building-good-containers.md#dependency-image).
20+
21+
While a Node.js developer may not need to setup the CI/CD pipleline a
22+
good understanding of their organizations pipeline is often valuable
23+
in order to understand what's needed to externalize configuration in
24+
the code they write as well as being able to investigate problems that
25+
may occur during different environments in the pipeline.
26+
27+
## Recommended Packages
28+
29+
N/A
30+
31+
## Guidance
32+
33+
The team's experiece is that there are most often two different ci/cd flows
34+
which are used at the same time:
35+
36+
* Testing on code check-in
37+
* Container pipeline - a pipeline to build and test images as they
38+
are promoted from development through to production.
39+
40+
While tools like [Source to image](https://github.com/openshift/source-to-image),
41+
[docker](https://www.docker.com/) or [podman](https://podman.io/) maybe used by
42+
the developer to test locally as documented in
43+
[Fully local development, container based](./dev-flows.md#fully-local-development-container-based) workflow,
44+
the developer does not push the image to source control. Instead,
45+
the images used for deployment are build as part of the container pipeline.
46+
47+
## Testing on code check-in
48+
49+
When a PR is made against a main branch in a source code repository (most often
50+
some form of git these days) initial testing is automatically kicked off
51+
using services like [Travis CI](https://www.travis-ci.com/) or
52+
[GitHub actions](https://github.com/features/actions). This level of testing
53+
starts with `unit` and `code quality` testing and the teams recommendations
54+
for this kind of testing for Node.js components are captured in the
55+
[Code Consistency](./code-consistency.md),
56+
[Testing](./testing.md), and
57+
[Code Coverage](./code-coverage.md) sections. Teams often
58+
then also test the PR by spinning up a container environment and runing some
59+
initial integration test. If you run check-in integration tests it is often useful to run both
60+
integration and unit tests in the container in order to capture a more complete picture
61+
of the Code Coverage achieved.
62+
63+
When a PR lands in the source code repository after passing
64+
those checks, the pipeline for building and testing images
65+
may be triggered automatically or it may be triggered separately
66+
at some interval.
67+
68+
Check-in testing is often configured to run on a number of Node.js
69+
versions in parallel and the team recommends that you test at least on the
70+
LTS version of Node.js that you currently deploy with along with
71+
later LTS versions in order to enable future upgrades.
72+
73+
While the check-in testing may not run on the image that flows
74+
through the container pipeline, the team tries to ensure
75+
that testing is on the same environment/architecture as used
76+
by the container pipeline. In addition, the team also recommends
77+
that the same is true for local testing done by developers.
78+
79+
## Container Pipeline
80+
81+
Once updates have passed the initial check-in testing, the container
82+
pipeline is kicked off. In the teams experience the pipeline may
83+
support a number of stages/environments including:
84+
85+
* Development
86+
* This environment often mirrors the main branch of each component
87+
and may sometimes not be working due to mistmatches in APIs/use of APIs.
88+
* Once tests pass in development, PRs may be automatically opened to
89+
update Staging to the new component levels.
90+
* Staging
91+
* Staging uses tagged versions of each component which are known to
92+
work together.
93+
* They may be multiple staging environments. One which
94+
mirrors production in terms of non-application components
95+
(versions of istio, kubernetes, etc.) and additional
96+
environments which reflect future target configurations
97+
for these components.
98+
* PRs may be automatically created to update component versions in
99+
production once tests pass in Staging but there is most often a
100+
formal sign off (by QA or other teams) for these to be accepted
101+
into production.
102+
* Pre-Production (optional)
103+
* pre-production may be used to allow customer testing/sign
104+
off before push to production.
105+
* Some teams use Staging instead of having a separate pre-production
106+
environment.
107+
* Production
108+
* Environment that hosts the customer facing service.
109+
110+
In addition to these environments, the team has also found that supporting
111+
the ability to spin up ephemeral environments to do specific testing when
112+
needed is advantageous.
113+
114+
The version of the component and the version of Node.js (through the base
115+
container image used) is fixed in the Development stage of the pipeline
116+
where the image is built for the component. That image is typically
117+
pushed to an internal registry and later steps in the pipeline use a tagged
118+
version of that image from the registry.
119+
120+
As the image for the Node.js component is built once and promoted
121+
through the pipeline stages, it is important that all configuration
122+
related to the environment is externalized so that environment specific
123+
values can be provided in each environment. This includes for example
124+
configuration for how to connect to databases and other services, the
125+
Node.js run configuration (production/development) and any other configuration
126+
information.
127+
128+
[Jekins](https://www.jenkins.io/) and
129+
[Tekton Pipelines](https://tekton.dev/) are common tools that have been
130+
used by the team to implement the container pipeline.
131+
132+
The team has found that it is advisable to use a separate git repository/branch
133+
to configure the versions of the components to be tested in each environment
134+
within the container pipeline. One commmon pattern the team has seen is using
135+
helm charts within this repo to configure the versions of the components used
136+
along with the configuration required for a given environment.
137+
138+
The team has found that it is useful to have shared helm charts for common application
139+
categories, deploying them helm parameters. In addition the team has also found
140+
it useful to separate configuration of the component versions from other
141+
configuration which does not change as often. This helps to isolate other
142+
changes from the more common component version changes.
143+
144+
## Security scans
145+
146+
Security checks are an important part of CI/CD pipelines. Typically the team
147+
deploys code and image scans in the check-in tests and/or the container pipeline.
148+
The benefit of running in the check-in tests helps developers validate that
149+
they have resolved reported issue.
150+
deploys checks in both the check-in tests as well as the container pipeline.
151+
152+
Tools like [mend](https://www.mend.io/), [Synk](https://snyk.io/) and those
153+
built into GitHub have been used for scanning in the check-in phase. Often
154+
a number of differents scans are required to cover all of the important aspects
155+
which include scans of:
156+
* application depencencies for vulnerabilities
157+
* os packages for vulnerabilities
158+
* source code using static analysis
159+
* container images for best practices (not running as root etc.)
160+
161+
Additional image based scans are then employed in the piplelines phases.
162+

0 commit comments

Comments
 (0)