Skip to content
This repository was archived by the owner on Apr 13, 2020. It is now read-only.

Commit a9fd7f9

Browse files
mtarngdennisseah
mtarng
and
dennisseah
authored
First pass at "getting started with spk" docs (#193)
* adding docs for getting started * adding service pipeline * adding TBD For mono vs single app * Adding service revision * adding info on Personal Access Token and other misc things (#187) * adding info on Personal Access Token and other misc things * remove -d parameter as required for create-variable-group command * Updating with a step by step guide * Adding Code to PAT requirements * minor formatting * typos fix Co-authored-by: Dennis Seah <dennis.seah@gmail.com>
1 parent d33f555 commit a9fd7f9

File tree

1 file changed

+284
-0
lines changed

1 file changed

+284
-0
lines changed

‎docs/getting-started.md‎

Lines changed: 284 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,284 @@
1+
# Managing a bedrock project with spk
2+
3+
This is a work in progress guide on managing a project with
4+
[bedrock](https://github.com/microsoft/bedrock/) workflows via the
5+
[spk](https://github.com/catalystcode/spk) CLI tool.
6+
7+
## Table of Contents
8+
9+
- [Managing a bedrock project with spk](#managing-a-bedrock-project-with-spk)
10+
- [Table of Contents](#table-of-contents)
11+
- [Using SPK with Bedrock](#using-spk-with-bedrock)
12+
- [Requirements](#requirements)
13+
- [Components](#components)
14+
- [Cloud Resource Diagram](#cloud-resource-diagram)
15+
- [SPK](#spk)
16+
- [Setup SPK](#setup-spk)
17+
- [Generating Personal Access Token](#generating-personal-access-token)
18+
- [Create spk config file](#create-spk-config-file)
19+
- [Initializing spk](#initializing-spk)
20+
- [Repositories](#repositories)
21+
- [Materialized Manifests Repository](#materialized-manifests-repository)
22+
- [Initializing the Materialized Manifests Repository](#initializing-the-materialized-manifests-repository)
23+
- [High Level Definition Repository](#high-level-definition-repository)
24+
- [Initializing the High Level Definition Repository](#initializing-the-high-level-definition-repository)
25+
- [Application Repositories](#application-repositories)
26+
- [Initializing an Application Repository](#initializing-an-application-repository)
27+
- [Adding a Service to a Application Repository](#adding-a-service-to-a-application-repository)
28+
- [Creating a Service Revision](#creating-a-service-revision)
29+
- [Varible Groups](#varible-groups)
30+
- [Pipelines](#pipelines)
31+
32+
## Using SPK with Bedrock
33+
34+
1. First, make sure [Requirements](#requirements) are met
35+
2. Create the required repositories (High Level Definition Repository,
36+
Materialized Manifests Repository) if they do not exist in the Azure Devops
37+
Project. Follow the guide
38+
[here](https://docs.microsoft.com/en-us/azure/devops/repos/git/create-new-repo?view=azure-devops#create-a-repo-using-the-web-portal)
39+
3. [Setup spk](#setup-spk)
40+
4. Optional:
41+
[Initialize the Materialized Manifest Repository](#initializing-the-materialized-manifests-repository)
42+
5. [Initialize the High Level Definition Repository](#initializing-the-high-level-definition-repository)
43+
6. [Initialize the Bedrock Application Repository](#initializing-an-application-repository)
44+
7. [Add a service to the Bedrock Application Repository](#adding-a-service-to-a-application-repository)
45+
8. Optional: [Create a Service Revision](#creating-a-service-revision)
46+
47+
**Notes:**
48+
49+
- Steps 2-5 typically only need to be done once. Multiple clusters may be
50+
configured to sync from the single Materialized Manifest Repositories, and
51+
multiple Project repositories can be pointed to the single High Level
52+
Definition Repository.
53+
- Step 6 can be repeated anytime you may need to create another Bedrock project.
54+
- Step 7 can be run as many times as required to add a service to a Bedrock
55+
project.
56+
57+
## Requirements
58+
59+
This guide assumes a few things:
60+
61+
1. The application code and supporting repositories are hosted on
62+
[Azure Devops](https://azure.microsoft.com/en-us/services/devops/).
63+
- If starting from scratch, then first create a new Azure Devops Organization
64+
following the guide
65+
[here](https://docs.microsoft.com/en-us/azure/devops/user-guide/sign-up-invite-teammates?view=azure-devops),
66+
then create a project following the guide
67+
[here](https://docs.microsoft.com/en-us/azure/devops/organizations/projects/create-project?view=azure-devops&tabs=preview-page).
68+
2. Inside the Azure Devops project, there exists repositories for:
69+
1. Materialized Manifests
70+
2. High Level Definitions Create the required repositories if they do not
71+
exist in the Azure Devops Project. Follow the guide
72+
[here](https://docs.microsoft.com/en-us/azure/devops/repos/git/create-new-repo?view=azure-devops#create-a-repo-using-the-web-portal)
73+
3. The application is packaged and run through a Docker image hosted on
74+
[Azure Container Registry](https://azure.microsoft.com/en-us/services/container-registry/)
75+
4. The user running `spk` has full access to the above resources.
76+
5. The user is running the latest `spk`
77+
[release](https://github.com/catalystcode/spk/releases).
78+
6. The user has
79+
[Azure CLI installed](https://docs.microsoft.com/en-us/cli/azure/?view=azure-cli-latest).
80+
81+
## Components
82+
83+
#### Cloud Resource Diagram
84+
85+
![spk resources](/docs/images/spk-resource-diagram.png "Bedrock SPK Resources")
86+
87+
### SPK
88+
89+
`spk` is the Command Line Interface that provides automation around defining and
90+
operating Kubernetes clusters with Bedrock principles.
91+
92+
#### Setup SPK
93+
94+
Make sure to download the latest version of `spk` from the
95+
[releases](https://github.com/catalystcode/spk/releases) page and add it to your
96+
PATH.
97+
98+
To setup a local configuration:
99+
100+
1. [Generate a Personal Access Token](#generating-personal-access-token)
101+
2. [Create a spk config file](#create-spk-config-file)
102+
3. [Initialize spk](#initializing-spk)
103+
104+
#### Generating Personal Access Token
105+
106+
Generate a new Personal Access Token (PAT) to grant `spk` permissions in the
107+
Azure Devops Project. Please grant PAT the following permissions:
108+
109+
- Build (Read & execute)
110+
- Code (Read, write, & manage)
111+
- Variable Groups (Read, create, & manage)
112+
113+
For help, follow the
114+
[guide](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=preview-page).
115+
116+
#### Create spk config file
117+
118+
Create a copy of `spk-config.yaml` from the starter
119+
[template](./../spk-config.yaml) with the appropriate values for the
120+
`azure_devops` section.
121+
122+
**Note:** This `spk-config.yaml` should not be commited anywhere, as it contains
123+
sensitive credentials.
124+
125+
#### Initializing spk
126+
127+
Run `spk init -f <spk-config.yaml>` where `<spk-config.yaml>` the path to the
128+
configuation file.
129+
130+
**Note:** When running `spk init -f <spk-config.yaml>`, `spk` will copy the
131+
values from the config file and store it into local memory elsewhere. If you
132+
wish to utilize `spk` with another project or target, then you must rerun
133+
`spk init` with another configuration first OR, you may overwrite each commands
134+
via flags.
135+
136+
### Repositories
137+
138+
#### Materialized Manifests Repository
139+
140+
This repository holds all the materialized kubernetes manifests that should be
141+
deployed to a cluster. If a cluster has been deployed via bedrock's terraform
142+
templates, then flux should be configured to point to this repository and will
143+
deploy all manifests in this repository to the cluster in a set interval.
144+
145+
##### Initializing the Materialized Manifests Repository
146+
147+
- [Create a repository in the given AzDO project.](https://docs.microsoft.com/en-us/azure/devops/repos/git/create-new-repo?view=azure-devops#create-a-repo-using-the-web-portal)
148+
- [Clone the repository.](https://docs.microsoft.com/en-us/azure/devops/repos/git/create-new-repo?view=azure-devops#clone-the-repo-to-your-computer)
149+
- Add a simple README to the repository
150+
```
151+
touch README.md
152+
echo "This is the Flux Manifest Repository." >> README.md
153+
git add -A
154+
git commit -m "Initializing Materialized Manifests repository with a README."
155+
git push -u origin --all
156+
```
157+
158+
#### High Level Definition Repository
159+
160+
This repository holds all the bedrock "High Level Definition" (HLD) yaml files
161+
and associated configurations. These HLDs and configs are consumed via
162+
[fabrikate](https://github.com/microsoft/fabrikate) to produce kubernetes
163+
manifests. This is typically done via an Azure DevOps pipeline, and the
164+
manifests output by fabrikate are placed into the Materialized Manifests
165+
repository.
166+
167+
##### Initializing the High Level Definition Repository
168+
169+
- [Create a repository in the given AzDO project.](https://docs.microsoft.com/en-us/azure/devops/repos/git/create-new-repo?view=azure-devops#create-a-repo-using-the-web-portal)
170+
- [Clone the repository.](https://docs.microsoft.com/en-us/azure/devops/repos/git/create-new-repo?view=azure-devops#clone-the-repo-to-your-computer)
171+
- Initialize via `spk`, this will add the fabrikate
172+
[cloud-native](https://github.com/microsoft/fabrikate-definitions/tree/master/definitions/fabrikate-cloud-native)
173+
stack as a initial sample component.
174+
```
175+
spk hld init
176+
git add -A
177+
git commit -m "Initializing HLD repository with the cloud-native stack."
178+
git push -u origin --all
179+
```
180+
- Deploy the Manifest Generation pipeline (optional flag parameters can be used
181+
if `spk` was not intialized)
182+
```
183+
spk hld install-manifest-pipeline
184+
```
185+
186+
#### Application Repositories
187+
188+
These repositories hold the application code and its associated Dockerfiles.
189+
Additionally, these repositories can hold one (single application) or more
190+
(monorepository) applications depending on usecase and configuration. Typically,
191+
each repository shold be configured with a "hld-lifecycle" Azure DevOps pipeline
192+
that will add all managed applications inside the repository to the High Level
193+
Definition Repository. Additionally, each application inside the repository
194+
should also have an associated Azure DevOps multi-stage pipeline that both
195+
builds and deploys the latest Docker image to Azure Container Registry and
196+
updates the associated configuation in the HLD repository with the latest image
197+
tag.
198+
199+
-TBD Section on packages directory and manging monorepositories vs single
200+
application repositories
201+
202+
##### Initializing an Application Repository
203+
204+
- [Create a repository in the given AzDO project.](https://docs.microsoft.com/en-us/azure/devops/repos/git/create-new-repo?view=azure-devops#create-a-repo-using-the-web-portal)
205+
- [Clone the repository.](https://docs.microsoft.com/en-us/azure/devops/repos/git/create-new-repo?view=azure-devops#clone-the-repo-to-your-computer)
206+
- Initialize the project via `spk`
207+
```
208+
spk project init
209+
git add -A
210+
git commit -m "Initializing application repository."
211+
git push -u origin --all
212+
```
213+
- Create Variable Group via `spk` (optional flag parameters can be used if `spk`
214+
was not intialized)
215+
```
216+
VARIABLE_GROUP_NAME=<my-vg-name>
217+
spk project create-variable-group $VARIABLE_GROUP_NAME -r $ACR_NAME -u $SP_APP_ID -t $SP_TENANT -p $SP_PASS
218+
git add -A
219+
git commit -m "Adding Project Variable Group."
220+
git push -u origin --all
221+
```
222+
where `ACR_NAME` is the name of the Azure Container Registry where the Docker
223+
Images will be served from and `SP_APP_ID`, `SP_PASS`, and, `SP_TENANT` are an
224+
associated Service Principal's ID, Password, and Tenant, that have Read and
225+
Write access to the ACR.
226+
- Deploy the lifecycle pipeline (optional flag parameters can be used if `spk`
227+
was not intialized)
228+
```
229+
spk project install-lifecycle-pipeline
230+
```
231+
232+
##### Adding a Service to a Application Repository
233+
234+
- [Clone the repository.](https://docs.microsoft.com/en-us/azure/devops/repos/git/create-new-repo?view=azure-devops#clone-the-repo-to-your-computer)
235+
- Create the service via `spk`, there are optional parameters that _should_ be
236+
used to configure the service and its associated helm charts (other optional
237+
flag parameters can be used if `spk` was not intialized)
238+
```
239+
SERVICE_NAME=<my-new-service-name>
240+
spk service create $SERVICE_NAME
241+
git add -A
242+
git commit -m "Adding $SERVICE_NAME to the repository."
243+
git push -u origin --all
244+
```
245+
- Deploy the service's multistage build pipeline via `spk` (optional flag
246+
parameters can be used if `spk` was not intialized)
247+
```
248+
spk service install-build-pipeline $SERVICE_NAME
249+
```
250+
251+
##### Creating a Service Revision
252+
253+
- Create and checkout a new git branch
254+
```
255+
git branch <my-new-feature-branch>
256+
git checkout <my-new-feature-branch>
257+
```
258+
- Make code changes and commit
259+
```
260+
echo "# My New Added File" >> myNewFile.md
261+
git add myNewFile.md
262+
git commit -m "Adding my new file"
263+
git push --set-upstream origin <my-new-feature-branch>
264+
```
265+
- Create Service Revision via `spk` (optional flag parameters can be used if
266+
`spk` was not intialized)
267+
```
268+
spk service create-revision
269+
```
270+
271+
### Varible Groups
272+
273+
TBD
274+
275+
- Done to hold secure credentials and secrets.
276+
277+
### Pipelines
278+
279+
TBD
280+
281+
- Application build & update (1 per application)
282+
- HLD lifecycle (adds applications to HLD repo)
283+
- HLD to Manifests (generates manifests via fabrikate and places manifests into
284+
flux's source repo)

0 commit comments

Comments
 (0)