Skip to content

docs: add ui override docs #262

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
popoveugene wants to merge 9 commits into
base: main
Choose a base branch
from
Open

docs: add ui override docs #262

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
1b21694
docs: add cmdb ui docs
popoveugene Mar 24, 2026
44ac88a
docs: wip
popoveugene Mar 24, 2026
97e8069
docs: add docs
popoveugene Mar 30, 2026
de6a512
docs: wip
popoveugene Mar 31, 2026
2043872
docs: wip
popoveugene Apr 28, 2026
79aa09b
docs: diagram update
popoveugene Apr 29, 2026
33e53b3
Merge branch 'main' into docs/update-doc
popoveugene Apr 29, 2026
94c6a0c
wip
popoveugene May 6, 2026
bbe89ad
docs: update Colly model
popoveugene May 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 111 additions & 0 deletions docs/analisys/colly-to-envgene-mapping.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
# Mapping of Colly attributes to EnvGene attributes

- [Mapping of Colly attributes to EnvGene attributes](#mapping-of-colly-attributes-to-envgene-attributes)
- [Description](#description)
- [Mapping table](#mapping-table)
- [`cluster-metadata.yml` example](#cluster-metadatayml-example)
- [`env_definition.yml` example](#env_definitionyml-example)
- [To Discuss](#to-discuss)
- [To Implement](#to-implement)

## Description

This document details how Colly attributes are persisted within the EnvGene Instance repository, specifying in which files and sections each attribute is stored.

## Mapping table

| Colly Object | Colly Attribute | Attribute Type in Colly | EnvGene Repository | Location in EnvGene | Description |
|--------------|-------------------------|---------------------------------------------------------------------------------------------------|--------------------|-------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
| Environment | `name` | string | instance | folder name in `<cluster-name>/<env-name>` | Environment name |
| Environment | `owners` | array of string | instance | `env_definition.metadata.owners` | Users responsible for the environment (Owners in Colly) |
| Environment | `teams` | array of string | instance | `env_definition.metadata.teams` | List of teams assigned to the environment |
| Environment | `status` | enum [`IN_USE`, `RESERVED`, `FREE`, `MIGRATING`, `DEPRECATED`] | instance | `env_definition.metadata.status` | Current status of the environment: in use, free, reserved, etc |
| Environment | `expirationDate` | string (LocalDate "yyyy-MM-dd") | instance | `env_definition.metadata.expirationDate` | Date until which the environment is allocated (expirationDate) |
| Environment | `type` | enum [`ENVIRONMENT`, `CSE_TOOLSET`, `DESIGN_TIME`, `APP_DEPLOYER`, `INFRASTRUCTURE`, `UNDEFINED`] | instance | `env_definition.metadata.type` | Technical category of the environment; type of environment |
| Environment | `role` | string (the list of allowed values is set via deployment parameter) | instance | `env_definition.metadata.role` | Usage role of the environment (e.g. Dev, QA), set by parameters |
| Environment | `labels` | array of string | instance | `env_definition.metadata.labels` | User-defined labels/tags for the environment |
| Environment | `description` | string | instance | `env_definition.metadata.description` | Free-form environment description |
| Environment | `accessGroups` | array of string | instance | `env_definition.security.accessGroups` | List of user groups that can work with the environment |
| Environment | `effectiveAccessGroups` | array of string | instance | `env_definition.security.effectiveAccessGroups` | Resolved full list of user groups (contains groups and their descendants). resolved based on `accessGroups` |
| Cluster | `name` | string | instance | folder name in `<cluster-name>/<env-name>` | Cluster name |
| Cluster | `description` | string | instance | `cluster-metadata.metadata.description` | Free-form cluster description |
| Cluster | `roAdGroups` | string | instance | `cluster-metadata.metadata.roAdGroups` | List of ro names and AD user groups under which all clusters of all projects will be managed |
| Cluster | `rwAdGroups` | string | instance | `cluster-metadata.metadata.rwAdGroups` | List of rw names and AD user groups under which all clusters of all projects will be managed |
| Cluster | `owners` | string | instance | `cluster-metadata.metadata.owners` | List of owners of the cluster |

Colly should support definition of owners names and groups for RW/RO access to clusters on project level in project git repository (same way as on global level) and accordingly provide it in project response. Current process of SaaS clusters provision consider both SaaS and project members to be mentioned in PaaS Zero Touch pipeline. New attributes are required for SSP to fit into existing flow with Provision Empty Cluster operation.

### `cluster-metadata.yml` example

location: `/environments/<cluster-name>/cloud-passport/`

```yaml
metadata:
# Optional
description: string
# Optional
# groups for RW/RO access to clusters
roAdGroups: list of strings
rwAdGroups: list of strings
owners: list of strings
```

### `env_definition.yml` example

```yaml
security: TBD
metadata:
owners:
- "user1"
- "user2"
teams:
- "team-a"
- "team-b"
status: "IN_USE"
expirationDate: "2024-12-31"
type: "ENVIRONMENT"
role: "Dev"
labels:
- "prod"
- "priority-high"
description: "very important env"
region: cm
```

## To Discuss

- [x] Is `ticketLinks` required?
- The attribute is not needed by users, so it was decided to remove it

- [x] Checkov [linting errors](https://github.com/Netcracker/qubership-envgene/actions/runs/18886399036/job/53902750553)
- Decided to ignore

- [x] Add the `deployPostfix` attribute to the Namespace?
- No

- [x] Remove the `deploymentVersion` attribute from the Environment?
- Yes

- [x] What is `deploymentStatus`?
- it is removed

- [x] Do we keep `cleanInstallationDate`? Is it computed based on SD_VERSIONS?
- it will be removed at [MS2](https://github.com/Netcracker/qubership-colly/issues/153)

- [x] How do we uniquely identify cluster, environment, and namespace in both services?

- [x] How do we separate the two services?
- Both services should return a unified schema for cluster, environment, and namespace, with all fields, but fill in only their own data. For example, for Environment:
- inventory-service: owners, teams, status, type, role, labels, description, expirationDate
- operational-service: cleanInstallationDate, monitoringData, deploymentStatus, lastSDDeploymentOperation, lastDeployedSDsByType
- ~~Two different models~~

- [ ] Where to store the `description` of a Cluster

- [ ] Using the OpenAPI specification as documentation
- How are descriptions and examples added to the OpenAPI spec?

## To Implement

- [ ] Change the formation of the macros `current_env.description` and `current_env.owners` taking into account the metadata section and migration
- [ ] Extend EnvGene `env_definition.yaml` JSON schema
284 changes: 284 additions & 0 deletions docs/analisys/project-repository.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,284 @@
# Project Repository

- [Project Repository](#project-repository)
- [Description](#description)
- [Repository Structure](#repository-structure)
- [Defaults](#defaults)
- [\[Defaults\] `parameters.yaml`](#defaults-parametersyaml)
- [\[Defaults\] `credentials.yaml`](#defaults-credentialsyaml)
- [Projects](#projects)
- [\[Projects\] `parameters.yaml`](#projects-parametersyaml)
- [\[Projects\] `credentials.yaml`](#projects-credentialsyaml)
- [Example](#example)
- [To discuss](#to-discuss)

## Description

This document describes the structure and contents of the Project repository.

## Repository Structure

```text
# AS IS
├── defaults
| └── defaults.yaml|yml
└── projects
└── <projectId>
└── parameters.yaml|yml
```

```text
├── defaults
| ├── parameters.yaml|yml
| └── credentials.yaml|yml
└── clusters
| ├── parameters.yaml|yml
| └── credentials.yaml|yml
└── projects
└── <projectId>
├── parameters.yaml|yml
└── credentials.yaml|yml
```

### Defaults

#### [Defaults] `parameters.yaml`

```yaml
# Optional
# List of rw/ro names and AD user groups under which all clusters of all projects will be created
# these parameters are used when creating a cluster
Used by SSP
clusters:
roAdGroups: list of strings
rwAdGroups: list of strings
owners: list of strings
```

#### [Defaults] `credentials.yaml`

Currently, this file has no contents

### Projects

#### [Projects] `parameters.yaml`

```yaml
# Mandatory
# Name of the customer
# Used by SSP
customerName: string
# Mandatory
# Name of the project
# Used by SSP and Colly
name: string
# Mandatory
# Type of the project
# Used by SSP
type: enum[ project, product]
# Optional
# List of groups with RW access rights to objects of this project
# Used by SSP
accessGroups:
- string
# Optional
# Platform type for clusters in this project
# "ocp" stands for OpenShift, "k8s" for generic Kubernetes
# Used by SSP
clustersPlatform: enum[ ocp, k8s ]
# Attribute used for Cloud Passport generation
# Used by SSP
mavenRepoName: string (SSP)
# Optional
# Full URL to the git group where project repositories are located
# На основе этого аттрибута вычисляются repositories[].url
# Или на всех repositories заданы url или задан этот аттрибут
# Used by SSP and Colly
gitGroupUrls:
- region: string
gitGroupUrl: string
# Optional
# Used by SSP and Colly
repositories:
- # Mandatory
# All repositories with type envgeneInstance must be specified because Colly uses them; url is mandatory for them
# Assumption: repository with type envgeneTemplate is only one per project
type: enum[ envgeneInstance, envgeneTemplate, clusterProvision, envProvision, solutionDeploy, DCL ]
# Optional
url: string
# Optional
# Not used now
# Token for repository access
# Pointer to Credential in credentials.yaml
token: creds.get('<credential-id>').secret
# Optional
# If not set, the "default" branch is used (as in GitLab/GitHub)
branch: string
# Optional
# Not used now
# Geographical region associated with the Environment. This attribute is user-defined
# Used in cases where specific `pipeline` repositories need to be used for certain environments
region: string
# Optional
# Only for type: envgeneTemplate
# TODO: discover from repository
envgeneArtifact:
# Mandatory
# Default EnvGene environment template artifact name (application from the application:version notation)
# For example platform:20251215.113905-22
name: string
# Mandatory
# Template name that is used by default when creating project environments.
# Should be included in templateDescriptorNames
defaultTemplateDescriptorName: string
```

#### [Projects] `credentials.yaml`

Contains [Credential](https://github.com/Netcracker/qubership-envgene/blob/main/docs/envgene-objects.md#credential) objects

```yaml
<credential-usernamePassword>:
type: usernamePassword
data:
username: string
password: string
<credential-secret>:
type: secret
data:
secret: string
```

Example:

```yaml
customerName: ACME
projectName: ACME-bss
repositories:
- type: envgeneInstance
url: https://git.acme.com/instance
token: instance-cred
- region: offsite-cn
type: pipeline
url: https://git.acme.com/pipeline
token: offsite-cn-pipeline-cred
- region: offsite-mb
type: pipeline
url: https://git.acmemb.com/pipelines
token: offsite-mb-pipeline-cred
- type: envgeneTemplate
url: https://git.acme.com/template
token: template-cred
branches:
- r25.3
- r25.4
envgeneTemplates:
envgene-acme:
- main
- dt
- dm
```

```yaml
instance-cred:
type: secret
data:
secret: "MGE3MjYwNTQtZGE4My00MTlkLWIzN2MtZjU5YTg3NDA2Yzk0MzlmZmViZGUtYWY4_PF84_ba"
template-cred:
type: secret
data:
secret: "MGE3MjYwNTQtZGE4My00MTlkLWIzN2MtZjU5YTg3NDA2Yzk0MzlmZmViZGUtYWY4_PF84_bb"
offsite-cn-pipeline-cred:
type: secret
data:
secret: "MGE3MjYwNTQtZGE4My00MTlkLWIzN2MtZjU5YTg3NDA2Yzk0MzlmZmViZGUtYWY4_PF84_bb"
offsite-mb-pipeline-cred:
type: secret
data:
secret: "MGE3MjYwNTQtZGE4My00MTlkLWIzN2MtZjU5YTg3NDA2Yzk0MzlmZmViZGUtYWY4_PF84_bb"
```

#### Example

Minimal project

```yaml
# parameters.yaml
customerName: ACME Corp
name: ACME BSS
type: project
repositories:
- type: envgeneInstance
url: https://gitlab.example.com/acme/instance.git
token: creds.get('gitlab-token').secret

# credentials.yaml
gitlab-token:
type: secret
data:
secret: dummy-token-value
```

Full project

```yaml
# parameters.yaml
customerName: ACME Corp
name: ACME OSS
type: project
accessGroups:
- devops-team
- developers
- qa
clustersPlatform: k8s
repositories:
- type: envgeneInstance
url: https://gitlab.example.com/acme/instance.git
token: creds.get('gitlab-token').secret
defaultBranch: release/26.1
region: cn

# credentials.yaml
gitlab-token:
type: secret
data:
secret: dummy-token-value
```

## To discuss

- [x] Use case for Colly using its own project repository:
1. Read all projects and extract the URL, token, and branches from the `envgeneInstance` repositories in order to display the environments from these projects.

- [x] Does each project currently have a different `accessGroups`?
- Yes, it is different

- [x] Is creating Project post/patch via the Colly API planned?
- Not right now, maybe in the future

- [x] `projectId` = customerAbbr + projectAbbr

- [x] Should the Project repository be used as the Maintenance inventory?
- yes

- [x] Need a mapping from environment to project. For example, an environment attribute `project`.
- Use case: find the DCL pipeline repository by environment
- Requestor - The Customer

- [x] global configuration

- [ ] `pipeline` is too generic, we need to specify the exact type of pipeline

- [x] `accessGroups` is a list of user groups for "clusters" or for Colly?
- list of groups that can work with the project => used for access control in SSP:
- who can see/edit which project/cluster/env

- [ ] `jiraCustomerName` - is it needed?

- [x] `envgeneArtifact`
- Short term:
- In the Repository, `envgeneArtifact.name` is set manually in Git
- Long term:
- need to decide whether Colly can discover:
- `envgeneArtifact.name`
- `envgeneArtifact.templateDescriptorNames`
Loading
Loading