From caa5f6fd4108c84fb2129660fb6a7370338a1724 Mon Sep 17 00:00:00 2001 From: Danny May Date: Tue, 6 Aug 2024 10:05:17 +0100 Subject: [PATCH 1/4] Add support for projects defining their own systems --- .../how-to-create-a-system.md | 61 ++++++++++++++++++ docs/images/delivery-project-id.png | Bin 0 -> 5179 bytes 2 files changed, 61 insertions(+) create mode 100644 docs/How-to-guides/Platform-Services/how-to-create-a-system.md create mode 100644 docs/images/delivery-project-id.png diff --git a/docs/How-to-guides/Platform-Services/how-to-create-a-system.md b/docs/How-to-guides/Platform-Services/how-to-create-a-system.md new file mode 100644 index 0000000..aa42956 --- /dev/null +++ b/docs/How-to-guides/Platform-Services/how-to-create-a-system.md @@ -0,0 +1,61 @@ +--- +title: How to create a system +summary: How to create a system for a project on ADP to use to group together services. +uri: https://defra.github.io/adp-documentation/How-to-guides/Platform-Services/how-to-create-a-system/ +authors: + - Danny May +date: 2024-08-05 +weight: 2 +--- + +# What is a system? + +A system is a label used to group together multiple related services. This label is recognized and used by backstage in order to make it clear what services interact with eachother. They are a concept which is provided by backstage out of the box, and is documented by them [here](https://backstage.io/docs/features/software-catalog/system-model#system) + +# How to create a system + +In order to create a system, you simply need to add a new definition for it to the [ADP software templates repository](https://github.com/DEFRA/adp-software-templates/tree/main/systems). There is [an example system](https://github.com/DEFRA/adp-software-templates/tree/main/systems/example.yaml) to show the format that should be used. Once this system is added, you need to add a link to it from the [all.yaml file](https://github.com/DEFRA/adp-software-templates/tree/main/systems/all.yaml). + +Once the system has been added and the `all.yaml` file has been updated, you will need to wait for the ADP portal to re-scan the repository which happens every hour. If you need the system to be available sooner than that, then an ADP admin can trigger a refresh at any time by requesting a refresh of the [project-systems location](https://portal.adp.defra.gov.uk/catalog/default/location/project-systems). + +## The `all.yaml` file + +The `all.yaml` file is what tells the ADP portal where to find the systems, and so every file containing a definition for a system must be pointed to by this file. To point to a new file, you will need to add a new entry to the `targets` array which should be the relative path from the `all.yaml` file to your new system file. + +`all.yaml` +```yaml +apiVersion: backstage.io/v1alpha1 +kind: Location +metadata: + name: project-systems + description: Systems defined and owned by projects using ADP. +spec: + targets: + # There is no need to modify any of the file above this point. + - ./another-projects-system.yaml + - ./my-system.yaml # Reference a system by a relative path like this. +``` + +## The `{system}.yaml` file + +Your system will actually be defined inside its own `.yaml` file. The name of this file should be the name of the system you are creating to make it easier to track which system is defined where. The format of this file should follow this example: + +`my-system.yaml` +```yaml +apiVersion: backstage.io/v1alpha1 +kind: System +metadata: + # This is the id of the system you want to create. It should be less than 100 characters long and + # only contain letters, numbers and hyphens. + name: my-system + # The description is meant to give users a bit of information about what sort of services are meant + # to be linked to this system and what it represents. This can be any text that you like, as long as it is valid yaml. + description: An example system, intended to be used to help projects to create their own systems. +spec: + # This needs to be a reference to the project that owns the system you are creating. This will always + # start with `group:default/`, and the ending bit should be the id of your project. You can find the id + # of your project in the url when you view it in the ADP portal, it will be the last segment of the URL + owner: "group:default/fcp-demo" +``` + +![Id of your delivery project](../../images/delivery-project-id.png "Id of your delivery project") \ No newline at end of file diff --git a/docs/images/delivery-project-id.png b/docs/images/delivery-project-id.png new file mode 100644 index 0000000000000000000000000000000000000000..28fcce2187b3e5297813657c3ec6dc7da7da2e43 GIT binary patch literal 5179 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 Date: Tue, 6 Aug 2024 12:47:40 +0100 Subject: [PATCH 2/4] Add system format --- .../Platform-Services/how-to-create-a-system.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/How-to-guides/Platform-Services/how-to-create-a-system.md b/docs/How-to-guides/Platform-Services/how-to-create-a-system.md index aa42956..dc117c4 100644 --- a/docs/How-to-guides/Platform-Services/how-to-create-a-system.md +++ b/docs/How-to-guides/Platform-Services/how-to-create-a-system.md @@ -14,7 +14,7 @@ A system is a label used to group together multiple related services. This label # How to create a system -In order to create a system, you simply need to add a new definition for it to the [ADP software templates repository](https://github.com/DEFRA/adp-software-templates/tree/main/systems). There is [an example system](https://github.com/DEFRA/adp-software-templates/tree/main/systems/example.yaml) to show the format that should be used. Once this system is added, you need to add a link to it from the [all.yaml file](https://github.com/DEFRA/adp-software-templates/tree/main/systems/all.yaml). +In order to create a system, you simply need to add a new definition for it to the [ADP software templates repository](https://github.com/DEFRA/adp-software-templates/tree/main/systems). There is [an example system](https://github.com/DEFRA/adp-software-templates/tree/main/systems/example.yaml) to show the format that should be used. Once this system is added, you need to add a link to it from the [all.yaml file](https://github.com/DEFRA/adp-software-templates/tree/main/systems/all.yaml). You will also need to choose a name for your system, which should be in the format `{delivery-project}-{system-name}-system` e.g. `fcp-demo-example-system` Once the system has been added and the `all.yaml` file has been updated, you will need to wait for the ADP portal to re-scan the repository which happens every hour. If you need the system to be available sooner than that, then an ADP admin can trigger a refresh at any time by requesting a refresh of the [project-systems location](https://portal.adp.defra.gov.uk/catalog/default/location/project-systems). @@ -46,8 +46,8 @@ apiVersion: backstage.io/v1alpha1 kind: System metadata: # This is the id of the system you want to create. It should be less than 100 characters long and - # only contain letters, numbers and hyphens. - name: my-system + # only contain letters, numbers and hyphens and be in the format `{delivery-project}-{system-name}-system` + name: fcp-demo-example-system # The description is meant to give users a bit of information about what sort of services are meant # to be linked to this system and what it represents. This can be any text that you like, as long as it is valid yaml. description: An example system, intended to be used to help projects to create their own systems. From 2f30e7fe75cbbb319bd9fa4f1f6554e44969caeb Mon Sep 17 00:00:00 2001 From: Danny May Date: Tue, 6 Aug 2024 12:48:14 +0100 Subject: [PATCH 3/4] Fix template --- .../How-to-guides/Platform-Services/how-to-create-a-system.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/How-to-guides/Platform-Services/how-to-create-a-system.md b/docs/How-to-guides/Platform-Services/how-to-create-a-system.md index dc117c4..d876cb7 100644 --- a/docs/How-to-guides/Platform-Services/how-to-create-a-system.md +++ b/docs/How-to-guides/Platform-Services/how-to-create-a-system.md @@ -14,7 +14,7 @@ A system is a label used to group together multiple related services. This label # How to create a system -In order to create a system, you simply need to add a new definition for it to the [ADP software templates repository](https://github.com/DEFRA/adp-software-templates/tree/main/systems). There is [an example system](https://github.com/DEFRA/adp-software-templates/tree/main/systems/example.yaml) to show the format that should be used. Once this system is added, you need to add a link to it from the [all.yaml file](https://github.com/DEFRA/adp-software-templates/tree/main/systems/all.yaml). You will also need to choose a name for your system, which should be in the format `{delivery-project}-{system-name}-system` e.g. `fcp-demo-example-system` +In order to create a system, you simply need to add a new definition for it to the [ADP software templates repository](https://github.com/DEFRA/adp-software-templates/tree/main/systems). There is [an example system](https://github.com/DEFRA/adp-software-templates/tree/main/systems/example.yaml) to show the format that should be used. Once this system is added, you need to add a link to it from the [all.yaml file](https://github.com/DEFRA/adp-software-templates/tree/main/systems/all.yaml). You will also need to choose a name for your system, which should be in the format `{delivery-project-id}-{system-name}-system` e.g. `fcp-demo-example-system` Once the system has been added and the `all.yaml` file has been updated, you will need to wait for the ADP portal to re-scan the repository which happens every hour. If you need the system to be available sooner than that, then an ADP admin can trigger a refresh at any time by requesting a refresh of the [project-systems location](https://portal.adp.defra.gov.uk/catalog/default/location/project-systems). @@ -46,7 +46,7 @@ apiVersion: backstage.io/v1alpha1 kind: System metadata: # This is the id of the system you want to create. It should be less than 100 characters long and - # only contain letters, numbers and hyphens and be in the format `{delivery-project}-{system-name}-system` + # only contain letters, numbers and hyphens and be in the format `{delivery-project-id}-{system-name}-system` name: fcp-demo-example-system # The description is meant to give users a bit of information about what sort of services are meant # to be linked to this system and what it represents. This can be any text that you like, as long as it is valid yaml. From 0fb982d2e0595037743a2be4a887bb71cd74b590 Mon Sep 17 00:00:00 2001 From: Danny May Date: Wed, 7 Aug 2024 16:32:10 +0100 Subject: [PATCH 4/4] Update docs and mkdocs --- docs/How-to-guides/Platform-Services/how-to-create-a-system.md | 2 +- mkdocs.yml | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/How-to-guides/Platform-Services/how-to-create-a-system.md b/docs/How-to-guides/Platform-Services/how-to-create-a-system.md index d876cb7..27eb20d 100644 --- a/docs/How-to-guides/Platform-Services/how-to-create-a-system.md +++ b/docs/How-to-guides/Platform-Services/how-to-create-a-system.md @@ -14,7 +14,7 @@ A system is a label used to group together multiple related services. This label # How to create a system -In order to create a system, you simply need to add a new definition for it to the [ADP software templates repository](https://github.com/DEFRA/adp-software-templates/tree/main/systems). There is [an example system](https://github.com/DEFRA/adp-software-templates/tree/main/systems/example.yaml) to show the format that should be used. Once this system is added, you need to add a link to it from the [all.yaml file](https://github.com/DEFRA/adp-software-templates/tree/main/systems/all.yaml). You will also need to choose a name for your system, which should be in the format `{delivery-project-id}-{system-name}-system` e.g. `fcp-demo-example-system` +In order to create a system, you simply need to add a new definition for it to the [ADP software templates repository](https://github.com/DEFRA/adp-software-templates/tree/main/systems). There is [an example system](https://github.com/DEFRA/adp-software-templates/tree/main/systems/example.yaml) to show the format that should be used. Once this system is added, you need to add a link to it from the [all.yaml file](https://github.com/DEFRA/adp-software-templates/tree/main/systems/all.yaml). You will also need to choose a name for your system, which should be in the format `{delivery-project-id}-{system-name}-system` e.g. `fcp-demo-example-system`. Once the system has been added and the `all.yaml` file has been updated, you will need to wait for the ADP portal to re-scan the repository which happens every hour. If you need the system to be available sooner than that, then an ADP admin can trigger a refresh at any time by requesting a refresh of the [project-systems location](https://portal.adp.defra.gov.uk/catalog/default/location/project-systems). diff --git a/mkdocs.yml b/mkdocs.yml index 7841404..a715dd7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -82,6 +82,7 @@ nav: - How to create a platform service: How-to-guides/Platform-Services/how-to-create-a-platform-service.md - How to deploy a platform service: How-to-guides/Platform-Services/how-to-deploy-a-platform-service.md - How to create a database: How-to-guides/Platform-Services/how-to-create-a-database.md + - How to create a system: How-to-guides/Platform-Services/how-to-create-a-system.md - Testing: - How to create an acceptance test: How-to-guides/Testing/how-to-create-acceptance-test.md - How to create a performance test: How-to-guides/Testing/how-to-create-performance-test.md