From 7b91db203c0bab21955b1fc9bfddcd3684f95536 Mon Sep 17 00:00:00 2001 From: Michael Tarng <20913254+mtarng@users.noreply.github.com> Date: Wed, 11 Mar 2020 01:15:00 -0700 Subject: [PATCH 1/3] Expanding rings guides on automation through spk and adding clarification on pipelines --- guides/manual-guide-to-rings.md | 27 ++++++++++----- guides/rings-101.md | 60 +++++++++++++++++++++++++++++++-- 2 files changed, 76 insertions(+), 11 deletions(-) diff --git a/guides/manual-guide-to-rings.md b/guides/manual-guide-to-rings.md index e1af0c947..3518abe34 100644 --- a/guides/manual-guide-to-rings.md +++ b/guides/manual-guide-to-rings.md @@ -276,12 +276,17 @@ variables: 4. Observe that committing to the `test-new-feature` should no longer trigger builds. -_Do note that deleting a `ring` presently does not remove the service and `ring` -from a cluster. This work is being -[tracked here](https://github.com/microsoft/bedrock/issues/858) but the -following instructions will detail how this can be done manually_ +**Note:** Deleting a `ring` presently does not remove the service and `ring` +from a cluster as the project lifecycle pipeline does not yet remove rings or +services from the HLD repository.\_ The work to support the automated removal of +rings and services is being +[tracked here.](https://github.com/microsoft/bedrock/issues/858) The following +instructions will detail how to remove a ring from a cluster by removing all +references to the ring in the HLD repository. -5. To remove a `ring` from a cluster, you must remove the `ring` component from +#### Removing the Ring from the cluster + +1. To remove a `ring` from a cluster, you must remove the `ring` component from the HLD. Recall the Pull Request generated by the `hld-lifecycle` pipeline when adding a `ring` to the `bedrock.yaml` file. The `ring` component is identified in the below diagram as `[Ring Component]`. In a clone of the HLD @@ -289,7 +294,7 @@ following instructions will detail how this can be done manually_ ![Sample HLD](./images/spk-hld-generated.png) -6. Finally, a user must modify the `component.yaml` within the directory +2. Finally, a user must modify the `component.yaml` within the directory identified by `[Service Component]` in the above diagram to no longer point to the directory that was deleted. For our sample service, `fabrikam`, with a ring to be removed, `test-new-feature`, the Service Component @@ -317,7 +322,13 @@ subcomponents: path: ./test-new-feature <-- DELETE --> ``` -7. Finally, after ensuring the `component.yaml` has been updated, and the `ring` +3. Make sure the above steps are followed for each service associated with the + `bedrock.yaml` that the `ring` was removed from. + +4. Finally, after ensuring the `component.yaml` has been updated, and the `ring` component directory in the HLD has been removed for the service, a user can commit and push the changes to a branch, merging it into the master branch of - their HLD, and triggering a rebuild of manifests deployed to the cluster. + their HLD. The subsequent triggered HLD to manifest pipeline will regenerate + the manifests, which will now exclude the removed ring, and the next flux + deployment will remove any associated k8s deployments and services from the + cluster. diff --git a/guides/rings-101.md b/guides/rings-101.md index ef5d9c46f..b890c91d4 100644 --- a/guides/rings-101.md +++ b/guides/rings-101.md @@ -76,9 +76,28 @@ Creating/adding a Ring is based around a single command: This command adds a new ring to your spk project and tracks it in projects `bedrock.yaml` file. Subsequently, the command walks through every service in -your project and updates their pipeline YAML to monitor the git branch the ring -corresponds to. Making every merge into the ring branch trigger a new -build/deployment of your ring. +your project and updates their build pipeline YAML to monitor the git branch the +ring corresponds to, so that every merge into the ring branch will trigger a new +build/deployment of your ring for the associated service. + +Commiting these changes to the `master` branch, or the branch where the +`hld-lifecycle.yaml` pipeline triggers off of, will trigger the project +lifecycle pipeline to add the ring to each service defined in the project +`bedrock.yaml` in the HLD repository. + +A sample HLD repository tree for a sample application repository +(`fabrikam-project`) with a service (`fabrikam`) and a newly added ring (`dev`): + +![Sample HLD](./images/spk-hld-generated.png) + +**Note:** There should only ever be a single lifecycle pipeline associated with +a project. The single branch on which it triggers, points to the "source of +truth" `bedrock.yaml`. This is the branch on which ring creation and deletion +needs to be commited to. + +**Note:** Because `spk` will add the branch triggers for each ring added to all +associated service build pipelines within a project, no additional pipelines +should be created when adding a ring. ### Deleting/Removing a Ring @@ -89,6 +108,41 @@ This command removes the ring from your `bedrock.yaml` file and walks through all the services in your project and removing the ring branch from the service pipeline YAML. +**Note:** The "default" ring cannot be deleted. If you wish to remove the ring +defined under `bedrock.yaml` with `isDefault: true`, you must first set another +ring to be the default ring via `spk ring set-default `. + +**Note:** Deleting a `ring` presently does not remove the service and `ring` +from a cluster as the project lifecycle pipeline does not yet remove rings or +services from the HLD repository.\_ The work to support the automated removal of +rings and services is being +[tracked here.](https://github.com/microsoft/bedrock/issues/858) To manually +remove the `ring` from the HLD repository and subsequently, the cluster, follow +the manual steps outlined +[here.](manual-guide-to-rings.md#removing-the-ring-from-the-cluster) + +### Setting the Default Ring + +For every bedrock project, there will be a default ring. By default, this is the +`master` ring, which corresponds to the master branch of the repository. + +For a `bedrock.yaml`: + +```yaml +rings: + master: + isDefault: true + develop: + isDefault: false +services: ... +``` + +the property `isDefault` denotes which `ring` is the default ring. + +Currently this property is only being used by the `spk service create-revision` +command. Details can be found +[here.](https://catalystcode.github.io/spk/commands/index.html#service_create-revision) + ### What Services Have What Rings? For each ring defined in your `bedrock.yaml` file, every services From 7e18ec1da1dedd8cf1839edfa4139f835d83eb31 Mon Sep 17 00:00:00 2001 From: Andre Briggs Date: Wed, 11 Mar 2020 01:30:12 -0700 Subject: [PATCH 2/3] Update rings-101.md Typo --- guides/rings-101.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/rings-101.md b/guides/rings-101.md index b890c91d4..6a85d5d58 100644 --- a/guides/rings-101.md +++ b/guides/rings-101.md @@ -61,7 +61,7 @@ Traefik2 to the correct _Ringed Service_ based on the service requested and the ## Rings & SPK -### Perquisites +### Prerequisites [SPK](https://github.com/CatalystCode/spk) is command line tool meant to ease the adoption of [Bedrock](https://github.com/microsoft/bedrock/) methodologies From 19315692713c8b9448ab1a2b686e195d52ab259d Mon Sep 17 00:00:00 2001 From: Michael Tarng <20913254+mtarng@users.noreply.github.com> Date: Wed, 11 Mar 2020 16:08:34 -0700 Subject: [PATCH 3/3] feedback --- guides/manual-guide-to-rings.md | 2 +- guides/rings-101.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/manual-guide-to-rings.md b/guides/manual-guide-to-rings.md index 3518abe34..b36ff06a6 100644 --- a/guides/manual-guide-to-rings.md +++ b/guides/manual-guide-to-rings.md @@ -278,7 +278,7 @@ variables: **Note:** Deleting a `ring` presently does not remove the service and `ring` from a cluster as the project lifecycle pipeline does not yet remove rings or -services from the HLD repository.\_ The work to support the automated removal of +services from the HLD repository. The work to support the automated removal of rings and services is being [tracked here.](https://github.com/microsoft/bedrock/issues/858) The following instructions will detail how to remove a ring from a cluster by removing all diff --git a/guides/rings-101.md b/guides/rings-101.md index 6a85d5d58..884063566 100644 --- a/guides/rings-101.md +++ b/guides/rings-101.md @@ -114,7 +114,7 @@ ring to be the default ring via `spk ring set-default `. **Note:** Deleting a `ring` presently does not remove the service and `ring` from a cluster as the project lifecycle pipeline does not yet remove rings or -services from the HLD repository.\_ The work to support the automated removal of +services from the HLD repository. The work to support the automated removal of rings and services is being [tracked here.](https://github.com/microsoft/bedrock/issues/858) To manually remove the `ring` from the HLD repository and subsequently, the cluster, follow