diff --git a/docs/envgene-objects.md b/docs/envgene-objects.md index d03a62b1..144b5c3c 100644 --- a/docs/envgene-objects.md +++ b/docs/envgene-objects.md @@ -10,9 +10,9 @@ - [ParameterSet (in Template repository)](#parameterset-in-template-repository) - [Resource Profile Override (in Template)](#resource-profile-override-in-template) - [Composite Structure Template](#composite-structure-template) - - [BG Domain Template](#bg-domain-template) - [Registry Definition Template](#registry-definition-template) - [Application Definition Template](#application-definition-template) + - [BG Domain Template](#bg-domain-template) - [System Credentials File (in Template repository)](#system-credentials-file-in-template-repository) - [Instance Repository Objects](#instance-repository-objects) - [Environment Instance Objects](#environment-instance-objects) @@ -102,17 +102,21 @@ cloud: # See details in https://github.com/Netcracker/qubership-envgene/blob/main/docs/template-inheritance.md overrides-parent: profile: - override-profile-name: string - parent-profile-name: string - baseline-profile-name: string - merge-with-parent: string - deployParameters: hashmap - e2eParameters: hashmap - technicalConfigurationParameters: hashmap - deployParameterSets: list - e2eParameterSets: list - technicalConfigurationParameterSets: list -composite_structure: string + override-profile-name: + parent-profile-name: + baseline-profile-name: + merge-with-parent: + deployParameters: + e2eParameters: + technicalConfigurationParameters: + deployParameterSets: + e2eParameterSets: + technicalConfigurationParameterSets: +# Optional +composite_structure: +# Optional +bg_domain: +# Optional namespaces: - # Optional # Path to the namespace template file @@ -309,14 +313,6 @@ satellites: type: "namespace" ``` -#### BG Domain Template - -This is a Jinja template file used to render the [BG Domain](#bg-domain) object for environments that use Blue-Green Domain (BGD) support. - -**Location:** `/templates/env-templates/{Group name}/bg-domain.yml.j2` - -[Macros](/docs/template-macros.md) are available for use when developing the template. - #### Registry Definition Template This is a Jinja template file used to render the [Registry Definition](#registry-definition) object. @@ -374,6 +370,30 @@ artifactId: "application-1" groupId: "org.qubership" ``` +#### BG Domain Template + +This is a Jinja template file used to render the [BG Domain](#bg-domain) object for environments that use Blue-Green Domain (BGD) support. + +**Location:** `/templates/env_templates/*/bg-domain.yml.j2` + +**Example:** + +```yaml +name: {{ current_env.environmentName ~ '-bg-domain' }} +type: bgdomain +originNamespace: + name: {{ current_env.get('additionalTemplateVariables', {}).get('ns_overrides', {}).get('origin-ns', current_env.environmentName ~ '-origin') }} + type: namespace +peerNamespace: + name: {{ current_env.get('additionalTemplateVariables', {}).get('ns_overrides', {}).get('peer-ns', current_env.environmentName ~ '-peer') }} + type: namespace +controllerNamespace: + name: {{ current_env.get('additionalTemplateVariables', {}).get('ns_overrides', {}).get('controller-ns', current_env.environmentName ~ '-controller') }} + type: namespace + credentials: controller-cred + url: https://controller-{{ current_env.get('additionalTemplateVariables', {}).get('ns_overrides', {}).get('controller-ns', current_env.environmentName ~ '-controller') }}.{{ current_env.cloud_passport.cloud.CLOUD_PUBLIC_HOST}} +``` + ### System Credentials File (in Template repository) This file contains [Credential](#credential) objects used by EnvGene to integrate with external systems like artifact registries, GitLab, GitHub, and others. @@ -631,7 +651,7 @@ satellites: #### BG Domain -The BG Domain object defines the Blue-Green Domain structure and namespace mappings for environments that use BGD support. This object is used for alias resolution in the `NS_BUILD_FILTER` parameter and BGD lifecycle management. +The BG Domain object defines the Blue-Green Domain structure and namespace mappings for environments that use BGD support. This object is used for alias resolution in the [`NS_BUILD_FILTER`](/docs/instance-pipeline-parameters.md#ns_build_filter) parameter and BGD lifecycle management. The BG Domain object is generated during Environment Instance generation based on: @@ -651,7 +671,7 @@ type: bgdomain # Mandatory # Origin namespace definition # Used to define the currently active BGD namespace -origin: +originNamespace: # Mandatory # The name of the origin namespace # Used for BGD alias resolution and lifecycle operations @@ -663,7 +683,7 @@ origin: # Mandatory # Peer namespace definition # Used to define the standby BGD namespace -peer: +peerNamespace: # Mandatory # The name of the peer namespace # Used for BGD alias resolution and lifecycle operations @@ -675,7 +695,7 @@ peer: # Mandatory # Controller namespace definition # Used for BGD lifecycle management and coordination -controller: +controllerNamespace: # Mandatory # The name of the controller namespace # Used by BGD operations for lifecycle coordination @@ -687,18 +707,42 @@ controller: # Mandatory # Credentials for accessing the BGD controller # Used for authentication with BG-Operator - credentialsIs: + credentials: # Mandatory # URL of the BG-Operator service # Used for BGD lifecycle operations url: ``` +When generating an Environment Instance that includes a BG Domain object, a [Credential](#credential) object with `usernamePassword` type is also generated in the [Environment Credentials File](#environment-credentials-file). The ID of the Credential uses the value `bg_domain.controllerNamespace.credentials`. +The [`inventory.config.updateCredIdsWithEnvName`](/docs/envgene-configs.md#env_definitionyml) mechanism works for this Credential as well as for all other Credentials. + +**Location:** `/environments///bg-domain.yml` + +**Example:** + +```yaml +bg_domain: + name: env-1-bg-domain + type: bgdomain + originNamespace: + name: env-1-bss-origin + type: namespace + peerNamespace: + name: env-1-bss-peer + type: namespace + controllerNamespace: + name: env-1-controller + credentials: controller-cred + type: namespace + url: https://controller-env-1-controller.qubership.org +``` + **BGD Alias Resolution:** Used by `NS_BUILD_FILTER` parameter to resolve BGD aliases: -- `${controller}` → controller namespace -- `${origin}` → origin namespaces -- `${peer}` → peer namespaces +- `@controller` → controller namespace +- `@origin` → origin namespaces +- `@peer` → peer namespaces ### Solution Descriptor diff --git a/docs/features/calculator-cli.md b/docs/features/calculator-cli.md index 71b1c048..e6052b19 100644 --- a/docs/features/calculator-cli.md +++ b/docs/features/calculator-cli.md @@ -48,6 +48,7 @@ - [\[Version 2.0\]\[Topology Context\] `k8s_tokens` Example](#version-20topology-context-k8s_tokens-example) - [\[Version 2.0\]\[Topology Context\] `environments` Example](#version-20topology-context-environments-example) - [\[Version 2.0\]\[Topology Context\] `cluster` Example](#version-20topology-context-cluster-example) + - [\[Version 2.0\]\[Topology Context\] `bg_domain` Example](#version-20topology-context-bg_domain-example) - [\[Version 2.0\] Runtime Parameter Context](#version-20-runtime-parameter-context) - [\[Version 2.0\]\[Runtime Parameter Context\] `parameters.yaml`](#version-20runtime-parameter-context-parametersyaml) - [\[Version 2.0\]\[Runtime Parameter Context\] `credentials.yaml`](#version-20runtime-parameter-context-credentialsyaml) @@ -1007,6 +1008,7 @@ This context only contains parameters generated by EnvGene: | **k8s_tokens** | Mandatory | Contains deployment tokens for each namespace in the Environment Instance. The value is derived from the `data.secret` property of the Credential specified via `defaultCredentialsId` attribute in the corresponding `Namespace` or parent `Cloud`. If the attribute is not defined at the `Namespace` level, it is inherited from the parent `Cloud`. If defined at both levels, the `Namespace` value takes precedence. Either the `Cloud` or `Namespace` must define `defaultCredentialsId`. This variable is located in `credentials.yaml` | None | [example](#version-20topology-context-k8s_tokens-example) | | **environments** | Mandatory | Contains **all** repository Environments, not just the one for which the Effective Set calculation was run. For each Environment, it includes the names of its contained namespaces. For each namespace, it provides a deploy postfix. The `deployPostfix` is taken from the Environment Instance's namespace folder name (a child of `Namespace` and parent of namespace.yml), which also acts as the namespace template name. This variable is located in `parameters.yaml` | None | [example](#version-20topology-context-environments-example) | | **cluster** | Mandatory | Contains information about the cluster where the Environment Instance is deployed. Includes cluster name, type, and other cluster-specific metadata taken from the [Cloud](/docs/envgene-objects.md#cloud) object. This variable is located in `parameters.yaml` | `{}` | [example](#version-20topology-context-cluster-example) | +| **bg_domain** | Mandatory | Contains the [BG Domain](/docs/envgene-objects.md#bg-domain) object from the Environment Instance for which the Effective Set is generated. Additionally, Calculator CLI adds two extra sensitive attribute `bg_domain.controllerNamespace.username` and `bg_domain.controllerNamespace.password` whose value is taken from the [Credential](/docs/envgene-objects.md#credential) with `usernamePassword` type and the ID from the `bg_domain.controllerNamespace.credentials` attribute. Non-sensitive parts of this variable are stored in `parameters.yaml`, while sensitive parts are stored in `credentials.yaml`. | `{}` | [example](#version-20topology-context-bg_domain-example) | ##### \[Version 2.0][Topology Context] `composite_structure` Example @@ -1065,15 +1067,45 @@ environments: ```yaml cluster: # Taken from the `apiUrl` attribute of the Cloud - api_url: "api.cl-03.managed.qubership.cloud" + api_url: "api.cl-03.managed.qubership.org" # Taken from the `apiPort` attribute of the Cloud api_port: "6443" # Taken from the `publicUrl` attribute of the Cloud - public_url: "apps.cl-03.managed.qubership.cloud" + public_url: "apps.cl-03.managed.qubership.org" # Taken from the `protocol` attribute of the Cloud protocol: "https" ``` +##### \[Version 2.0][Topology Context] `bg_domain` Example + +**`parameters.yaml`** + +```yaml +bg_domain: + name: env-1-bg-domain + type: bgdomain + originNamespace: + name: env-1-bss-origin + type: namespace + peerNamespace: + name: env-1-bss-peer + type: namespace + controllerNamespace: + name: env-1-controller + type: namespace + credentials: controller-cred + url: https://controller-env-1-controller.qubership.org +``` + +**`credentials.yaml`** + +```yaml +bg_domain: + controllerNamespace: + username: user + password: glpat-qzypHtKK +``` + #### [Version 2.0] Runtime Parameter Context This file's parameters define a **distinct** context for managing application behavior without redeployment. These parameters can be applied without redeploying the application. diff --git a/docs/features/namespace-render-filtering.md b/docs/features/namespace-render-filtering.md index 2f166819..fe576601 100644 --- a/docs/features/namespace-render-filtering.md +++ b/docs/features/namespace-render-filtering.md @@ -16,9 +16,9 @@ You can set the value of `NS_BUILD_FILTER` in two ways: You can use BG Domain role aliases as namespace selectors: -- `${controller}` - controller namespace -- `${origin}` - origin namespace -- `${peer}` - peer namespace +- `@controller` - controller namespace +- `@origin` - origin namespace +- `@peer` - peer namespace EnvGene resolves these aliases using the [BG Domain](/docs/envgene-objects.md#bg-domain) object. To use aliases, the BG Domain object must exist in the Environment. @@ -40,7 +40,7 @@ The following operators are available: ### Update all except the peer NS ```yaml -NS_BUILD_FILTER: "! ${peer}" +NS_BUILD_FILTER: "! @peer" # or NS_BUILD_FILTER: "! env-name-peer" ``` @@ -48,7 +48,7 @@ NS_BUILD_FILTER: "! env-name-peer" ### Update only the peer NS ```yaml -NS_BUILD_FILTER: "${peer}" +NS_BUILD_FILTER: "@peer" # or NS_BUILD_FILTER: "env-name-peer" ``` @@ -65,10 +65,10 @@ NS_BUILD_FILTER is not provided ```yaml # Update controller and origin -NS_BUILD_FILTER: "${peer},${origin}" +NS_BUILD_FILTER: "@peer,@origin" # Update all except peer and controller -NS_BUILD_FILTER: "! ${peer},${controller}" +NS_BUILD_FILTER: "! @peer,@controller" # Update specific namespaces by name NS_BUILD_FILTER: "env-name-api,env-name-frontend" diff --git a/docs/template-macros.md b/docs/template-macros.md index c05c3a81..32185560 100644 --- a/docs/template-macros.md +++ b/docs/template-macros.md @@ -51,6 +51,17 @@ - [`CONSUL_PUBLIC_URL`](#consul_public_url) - [`CONSUL_ADMIN_TOKEN`](#consul_admin_token) - [`CONSUL_ENABLED`](#consul_enabled) + - [`ORIGIN_NAMESPACE`](#origin_namespace) + - [`PEER_NAMESPACE`](#peer_namespace) + - [`CONTROLLER_NAMESPACE`](#controller_namespace) + - [`BG_CONTROLLER_URL`](#bg_controller_url) + - [`BG_CONTROLLER_LOGIN`](#bg_controller_login) + - [`BG_CONTROLLER_PASSWORD`](#bg_controller_password) + - [`BASELINE_ORIGIN`](#baseline_origin) + - [`BASELINE_CONTROLLER`](#baseline_controller) + - [`BASELINE_PEER`](#baseline_peer) + - [`PUBLIC_IDENTITY_PROVIDER_URL`](#public_identity_provider_url) + - [`PRIVATE_IDENTITY_PROVIDER_URL`](#private_identity_provider_url) - [Credential Macro](#credential-macro) - [Deprecated Macros](#deprecated-macros) - [Deprecated Jinja Macros](#deprecated-jinja-macros) @@ -60,6 +71,8 @@ - [`deployer`](#deployer) - [Deprecated Credential Macros](#deprecated-credential-macros) - [`${envgene.creds.get('').username|password|secret}`](#envgenecredsgetcred-idusernamepasswordsecret) + - [Deprecated Calculator CLI macros](#deprecated-calculator-cli-macros) + - [`BASELINE_PROJ`](#baseline_proj) This documentation provides a list of macros that can be used in environment templates and environment-specific parameter sets. @@ -993,6 +1006,210 @@ Value is get from `vaultConfig.enable` of the Environment's [Cloud](/docs/envgen **Usage in sample:** TBD +### `ORIGIN_NAMESPACE` + +--- +**Description:** Name of origin namespace of the BG Domain. + +The value is taken from the origin namespace definition in the [BG Domain](/docs/envgene-objects.md#bg-domain) object. + +If the BG Domain is absent, the value is the same as `${NAMESPACE}`. + +**Type:** String + +**Default Value:** `${NAMESPACE}` + +**Basic usage:** + +`origin_ns: "${ORIGIN_NAMESPACE}"` + +**Usage in sample:** TBD + +### `PEER_NAMESPACE` + +--- +**Description:** Name of peer namespace of the BG Domain. + +The value is taken from the peer namespace definition in the [BG Domain](/docs/envgene-objects.md#bg-domain) object. + +If value is not provided, it means that namespace doesn't participate in BG Domain. + +**Type:** String + +**Default Value:** None + +**Basic usage:** + +`peer_ns: "${PEER_NAMESPACE}"` + +**Usage in sample:** TBD + +### `CONTROLLER_NAMESPACE` + +--- +**Description:** Name of controller namespace of the BG Domain. + +The value is taken from the controller namespace definition in the [BG Domain](/docs/envgene-objects.md#bg-domain) object. + +If value is not provided, it means that namespace doesn't participate in BG Domain. + +**Type:** String + +**Default Value:** None + +**Basic usage:** + +`controller_ns: "${CONTROLLER_NAMESPACE}"` + +**Usage in sample:** TBD + +### `BG_CONTROLLER_URL` + +--- +**Description:** URL of bluegreen-controller ingress. + +The value is calculated as `${protocol.toLowerCase()}://bluegreen-controller-${NAMESPACE}.$customHost` where customHost is Cloud Private URL, Cloud Public URL, or Cloud API URL. + +**Type:** String + +**Default Value:** None + +**Basic usage:** + +`bg_controller: "${BG_CONTROLLER_URL}"` + +**Usage in sample:** TBD + +### `BG_CONTROLLER_LOGIN` + +--- +**Description:** Username from the bluegreen domain credential id. + +The value is taken from the controller credential in the [BG Domain](/docs/envgene-objects.md#bg-domain) object. + +**Type:** String + +**Default Value:** `bgoperator` + +**Basic usage:** + +`bg_login: "${BG_CONTROLLER_LOGIN}"` + +**Usage in sample:** TBD + +### `BG_CONTROLLER_PASSWORD` + +--- +**Description:** Password from the bluegreen domain credential id. + +The value is taken from the controller credential in the [BG Domain](/docs/envgene-objects.md#bg-domain) object. + +**Type:** String + +**Default Value:** None + +**Basic usage:** + +`bg_password: "${BG_CONTROLLER_PASSWORD}"` + +**Usage in sample:** TBD + +### `BASELINE_ORIGIN` + +--- +**Description:** Value is provided if current namespace is a satellite (regardless if it is a single namespace satellite or a BG domain satellite). + +Contains name of: + +- Origin namespace name if baseline is a BG domain +- Baseline namespace name if baseline is a namespace, not a BG domain + +Value is used as a replacement of `BASELINE_PROJ` value that should be deprecated. + +**Type:** String + +**Default Value:** None + +**Basic usage:** + +`baseline_origin: "${BASELINE_ORIGIN}"` + +**Usage in sample:** TBD + +### `BASELINE_CONTROLLER` + +--- +**Description:** Value is provided if current namespace is a satellite (regardless if it is a single namespace satellite or a BG domain satellite). + +Contains name of Controller namespace if baseline is a BG domain. Will not be provided if baseline is a namespace, not a BG domain. + +**Type:** String + +**Default Value:** None + +**Basic usage:** + +`baseline_controller: "${BASELINE_CONTROLLER}"` + +**Usage in sample:** TBD + +### `BASELINE_PEER` + +--- +**Description:** Value is provided if current namespace is a satellite (regardless if it is a single namespace satellite or a BG domain satellite). + +Contains name of Peer namespace if baseline is a BG domain. Will not be provided if baseline is a namespace, not a BG domain. + +**Type:** String + +**Default Value:** None + +**Basic usage:** + +`baseline_peer: "${BASELINE_PEER}"` + +**Usage in sample:** TBD + +### `PUBLIC_IDENTITY_PROVIDER_URL` + +--- +**Description:** Defines URL of public gateway where IDP is published. In case of composite deployment this URL should point to gateway in baseline even if current namespace is a satellite. + +Calculation rules: + +- `PUBLIC_IDENTITY_PROVIDER_URL` from `BASELINE_ORIGIN` namespace if `BASELINE_ORIGIN` is defined +- `${PUBLIC_GATEWAY_URL}` in other cases + +**Type:** String + +**Default Value:** Calculated based on baseline configuration + +**Basic usage:** + +`public_idp: "${PUBLIC_IDENTITY_PROVIDER_URL}"` + +**Usage in sample:** TBD + +### `PRIVATE_IDENTITY_PROVIDER_URL` + +--- +**Description:** Defines URL of private gateway where IDP is published. In case of composite deployment this URL should point to gateway in baseline even if current namespace is a satellite. + +Calculation rules: + +- `PRIVATE_IDENTITY_PROVIDER_URL` from `BASELINE_ORIGIN` namespace if `BASELINE_ORIGIN` is defined +- `${PRIVATE_GATEWAY_URL}` in other cases + +**Type:** String + +**Default Value:** Calculated based on baseline configuration + +**Basic usage:** + +`private_idp: "${PRIVATE_IDENTITY_PROVIDER_URL}"` + +**Usage in sample:** TBD + ## Credential Macro --- @@ -1056,3 +1273,17 @@ k8s_token: ${creds.get('k8s-cred').secret} **Description:** This macro was used for processing system sensitive parameters—parameters that EnvGene uses to integrate itself with external systems, such as the login and password for a registry or a token for a GitLab instance. **Replacement**: [`${creds.get('').username|password|secret}`](#credential-macro) + +### Deprecated Calculator CLI macros + +#### `BASELINE_PROJ` + +--- +**Description:** Defines baseline namespace if current namespace is a satellite. + +Calculation rules: + +- If baseline is a Bluegreen Domain: `BASELINE_PROJ = BASELINE_CONTROLLER` +- Otherwise (if baseline is a standalone namespace): `BASELINE_PROJ = BASELINE_ORIGIN` + +**Replacement**: [`BASELINE_ORIGIN`](#baseline_origin)