From 62f0e8388fa72f470a9060a45418c8cbfab5dcd5 Mon Sep 17 00:00:00 2001 From: racfop Date: Mon, 10 Jul 2023 09:51:18 -0700 Subject: [PATCH 1/2] Annotations --- content/en/docs/annotations/_index.md | 103 ++++++++++++++++++ .../merge-humanitec-deployments.md | 2 +- content/en/docs/extensions/_index.md | 10 +- .../en/docs/reference/score-spec-reference.md | 14 +-- 4 files changed, 117 insertions(+), 12 deletions(-) create mode 100644 content/en/docs/annotations/_index.md diff --git a/content/en/docs/annotations/_index.md b/content/en/docs/annotations/_index.md new file mode 100644 index 00000000..fea190f5 --- /dev/null +++ b/content/en/docs/annotations/_index.md @@ -0,0 +1,103 @@ +--- +title: "Annotations" +linkTitle: "Annotations" +weight: 5 +description: > + This section covers annotations, which are used to provide additional metadata for resources. +--- + +One of the key features of Score is the ability to attach additional metadata to your resources using Annotations. + +## How to use annotations + +Use annotations to provide additional metadata for resources. Annotations are defined as a map with keys and values that provide additional information to a resource description. + +To provide an annotation for a resource, specify the following: + +```yml +resources: + your-resource: + metadata: + annotations: + your-annotation-key: your-annotation-value +``` + +The resource `your-resource` has a single annotation with the key `your-annotation-key` and the value `your-annotation-value`. + +## Why use Annotations? + +There are several reasons why you might want to use Annotations in your Score files: + +- **Informational hints**: Annotations are used to provide additional information to anyone or anything interacting with your resources, defined in your Score file. This could be helpful instructions for developers, or hints to tools and systems about how to handle a certain resource. +- **Shared resources**: Annotations are used to provide additional information to anyone or anything interacting with your resources, defined in your Score file. This could be helpful instructions for developers, or hints to tools and systems about how to handle a certain resource. +- **System-specific info**: Some systems and tools that interact with your Score resources might require certain metadata to be present to operate correctly, such as shared resources. Annotations provide a flexible way to supply this metadata. + +### Annotations example + +The following is an example of using an annotation to provide additional metadata for a database service. + +```yml +apiVersion: score.dev/v1b1 +metadata: + name: hello-annotations + +service: + ports: + www: + port: 80 + targetPort: 8080 + +containers: + hello: + image: busybox + command: + - "/bin/echo" + args: + - "Hello Annotations" + +resources: + db: + metadata: + annotations: + "my.org/version": "0.1" + type: postgres + properties: + host: + type: string + default: localhost + required: true + port: + default: 5432 +``` + +### Shared resource example + +The following is an example of using an annotation to provide additional metadata for a shared resource. + +```yml +resources: + shared-db: + metadata: + annotations: + score.humanitec.io/resId: shared.postgres-db + type: postgres + properties: + host: localhost + port: 5432 +``` + +In this example, a shared PostgreSQL database is defined with the name `shared-db`. +The annotation `score.humanitec.io/resId` is used to provide a unique identifier for this shared resource (`shared.postgres-db`). +This identifier is used by the Humanitec system to map and manage this shared resource across multiple services or applications. + +{{% alert %}} +The type and properties of the resource would depend on the type of resource you are trying to define. +{{% /alert %}} + +Now, any service or application that needs to use this shared resource can simply reference the identifier `shared.postgres-db`. + +## Annotations vs. extension files + +Annotations are used to provide additional metadata as a hint for the individual Score file instead of using the extensions file. + +It is recommended to use annotations instead of [extension files]({{< relref "../extensions/_index.md" >}}), as annotations help ensure consistency across your environments and deployments, since your Workload information is stored in one file. diff --git a/content/en/docs/dependencies/merge-humanitec-deployments.md b/content/en/docs/dependencies/merge-humanitec-deployments.md index bc27ca3e..b0f06655 100644 --- a/content/en/docs/dependencies/merge-humanitec-deployments.md +++ b/content/en/docs/dependencies/merge-humanitec-deployments.md @@ -120,4 +120,4 @@ The output of the command will be a delta file that contains the changes made to } ``` -Merging two workload deployments together using the `--delta` flag can simplify the deployment process by allowing you to deploy multiple Workloads as a single release. You can merge your Workload deployments seamlessly and manage your application deployments more effectively. \ No newline at end of file +Merging two workload deployments together using the `--delta` flag can simplify the deployment process by allowing you to deploy multiple Workloads as a single release. You can merge your Workload deployments seamlessly and manage your application deployments more effectively. diff --git a/content/en/docs/extensions/_index.md b/content/en/docs/extensions/_index.md index c5de705c..812d0172 100644 --- a/content/en/docs/extensions/_index.md +++ b/content/en/docs/extensions/_index.md @@ -1,11 +1,16 @@ --- title: "Manage extension files" linkTitle: "Manage extensions" -weight: 4 +weight: 6 description: > Manage routes as resources, in your Humanitec applications. --- +{{% alert %}} + +> It is recommned to use [annotations]({{< relref "../annotations/_index.md" >}} "Annotations") instead of extension files, as annotations help ensure consistency across your enviroments and deployments, since your Workload information is stored in one file. +> {{% /alert %}} + Score supports extension files. ## Overview @@ -13,8 +18,7 @@ Score supports extension files. {{% alert %}} > The `humanitec.score.yaml` extension is used by [`score-humantic` Score implementation (CLI)](https://github.com/score-spec/score-humanitec). This is an optional configuration specific for Humanitec's routes as a resource and services accounts. - -{{% /alert %}} +> {{% /alert %}} diff --git a/content/en/docs/reference/score-spec-reference.md b/content/en/docs/reference/score-spec-reference.md index 9ca8066a..b70f5c04 100644 --- a/content/en/docs/reference/score-spec-reference.md +++ b/content/en/docs/reference/score-spec-reference.md @@ -108,13 +108,12 @@ resources: In general, `resource-type` has no meaning for Score, but it can affect how the targeted Score implementation tool resolves the resource. The following conventions are _reserved_ resource types. -| Resource type | `score-compose` | `score-humanitec` | -| ------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `environment` | Translates to the environment variables references. For example: `${PROPERTY-NAME}`. | Translates to the application values references. For example: `${values.property-name}`. | -| `volume` | Translates into a reference to the external volume. This reference is usually used in a container’s volume mount specification. | Translates into a reference to the external volume. This reference is usually used in a container’s volume mount specification. | -| `service` | N/A | Translates to the module properties references. For example: `${modules.service-name.property-name}`. | -| `workload` | N/A | Reserved resource type. Its usage may lead to compatibility issues with future releases of [score-humanitec](https://github.com/score-spec/score-humanitec).| - +| Resource type | `score-compose` | `score-humanitec` | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `environment` | Translates to the environment variables references. For example: `${PROPERTY-NAME}`. | Translates to the application values references. For example: `${values.property-name}`. | +| `volume` | Translates into a reference to the external volume. This reference is usually used in a container’s volume mount specification. | Translates into a reference to the external volume. This reference is usually used in a container’s volume mount specification. | +| `service` | N/A | Translates to the module properties references. For example: `${modules.service-name.property-name}`. | +| `workload` | N/A | Reserved resource type. Its usage may lead to compatibility issues with future releases of [score-humanitec](https://github.com/score-spec/score-humanitec). | ### Referencing resources @@ -368,4 +367,3 @@ containers: - name: Custom-Header value: Awesome ``` - From ec4e8e283cc6141e00f06ab13f58202206e3d2df Mon Sep 17 00:00:00 2001 From: racfop Date: Wed, 12 Jul 2023 08:18:39 -0700 Subject: [PATCH 2/2] Adds reference --- content/en/docs/reference/score-spec-reference.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/content/en/docs/reference/score-spec-reference.md b/content/en/docs/reference/score-spec-reference.md index b70f5c04..dce83631 100644 --- a/content/en/docs/reference/score-spec-reference.md +++ b/content/en/docs/reference/score-spec-reference.md @@ -71,6 +71,9 @@ It is up to {{< glossary_tooltip text="Score implementation (CLI)" term_id="scor ```yaml resources: [resource-name]: + metadata: # optional + annotations: # optional + [annotation-name]: [value] type: [resource-type] properties: # optional [property-name]: @@ -87,6 +90,13 @@ resources: - **Type**: string. - **Constraints**: alphanumeric string. +**`metadata`**: an optional property that specifies additional resource metadata. + +- **`Type`**: object. + - **`annotations`**: an optional property that specifies metadata annotations. + - **`Type`**: object. + - **`Constraints`**: alphanumeric string key-value pairs. + `resource-type`: specifies the resource in the target environment. - **Type**: string.