diff --git a/301redirects.json b/301redirects.json index ec3b329ae1..e4cee1db3c 100644 --- a/301redirects.json +++ b/301redirects.json @@ -1807,6 +1807,46 @@ "destination": "/docs/fast_data/configuration/cast_functions", "addedOn": "2024-10-23" }, + "/docs/marketplace/add_to_marketplace/create_your_company_marketplace": { + "destination": "/docs/software-catalog/manage-items/overview-manage-items", + "addedOn": "2024-11-19" + }, + "/docs/marketplace/add_to_marketplace/add_item_by_type/add_plugin": { + "destination": "/docs/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_plugin", + "addedOn": "2024-11-19" + }, + "/docs/marketplace/add_to_marketplace/add_item_by_type/add_template_or_example": { + "destination": "/docs/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_template_or_example", + "addedOn": "2024-11-19" + }, + "/docs/marketplace/add_to_marketplace/add_item_by_type/add_application": { + "destination": "/docs/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_application", + "addedOn": "2024-11-19" + }, + "/docs/marketplace/add_to_marketplace/add_item_by_type/add_sidecar": { + "destination": "/docs/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_sidecar", + "addedOn": "2024-11-19" + }, + "/docs/marketplace/add_to_marketplace/add_item_by_type/add_custom_resource": { + "destination": "/docs/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_infrastructure_resource", + "addedOn": "2024-11-19" + }, + "/docs/marketplace/add_to_marketplace/manage_marketplace_items": { + "destination": "/docs/software-catalog/manage-items/overview-manage-items", + "addedOn": "2024-11-19" + }, + "/docs/marketplace/add_to_marketplace/marketplace_items_accessibility": { + "destination": "/docs/software-catalog/catalog-and-marketplace/overview-catalog-and-marketplace", + "addedOn": "2024-11-19" + }, + "/docs/marketplace/add_to_marketplace/change_marketplace_item_visibility": { + "destination": "/docs/software-catalog/catalog-and-marketplace/overview-catalog-and-marketplace", + "addedOn": "2024-11-19" + }, + "/docs/marketplace/add_to_marketplace/declarative_marketplace": { + "destination": "/docs/software-catalog/manage-items/declarative-approach", + "addedOn": "2024-11-19" + }, "/docs/data_catalog/data_catalog_frontend": { "destination": "/docs/data_catalog/frontend/overview", "addedOn": "2024-11-26" diff --git a/docs/cli/miactl/20_setup.md b/docs/cli/miactl/20_setup.md index 1c7c70c9bc..cc4742cfa0 100644 --- a/docs/cli/miactl/20_setup.md +++ b/docs/cli/miactl/20_setup.md @@ -38,13 +38,13 @@ If you have [Golang] installed with a version >= 1.13 in your system and you hav install `miactl` like this: ```sh -go install github.com/mia-platform/miactl/cmd/miactl@v0.15.0 +go install github.com/mia-platform/miactl/cmd/miactl@v0.16.0 ``` Or like this if the `install` command is not available ```sh -go get -u github.com/mia-platform/miactl/cmd/miactl@0.15.0 +go get -u github.com/mia-platform/miactl/cmd/miactl@0.16.0 ``` #### Binary Download @@ -53,11 +53,11 @@ You can install `miactl` with the use of `curl` or `wget` and downloading the la choosing the correct platform and operating system: ```sh -curl -fsSL https://github.com/mia-platform/miactl/releases/download/v0.15.0/miactl-linux-amd64 -o /tmp/miactl +curl -fsSL https://github.com/mia-platform/miactl/releases/download/v0.16.0/miactl-linux-amd64 -o /tmp/miactl ``` ```sh -wget -q https://github.com/mia-platform/miactl/releases/download/v0.15.0/miactl-linux-amd64 -O /tmp/miactl +wget -q https://github.com/mia-platform/miactl/releases/download/v0.16.0/miactl-linux-amd64 -O /tmp/miactl ``` After you have downloaded the file you can validate it against the checksum you can find at this [url] running the @@ -85,7 +85,7 @@ sudo mv /tmp/miactl /usr/local/bin If you want to run the cli in its environment or you want to test the cli you can use the Docker image: ```sh -docker run ghcr.io/mia-platform/miactl:v0.15.0 miactl +docker run ghcr.io/mia-platform/miactl:v0.16.0 miactl ``` ### Windows @@ -184,7 +184,7 @@ only via APIs. [Homebrew]: https://brew.sh "The Missing Package Manager for macOS (or Linux)" [Golang]: https://go.dev "Build simple, secure, scalable systems with Go" -[url]: https://github.com/mia-platform/miactl/releases/download/v0.15.0/checksums.txt "miactl checksums" +[url]: https://github.com/mia-platform/miactl/releases/download/v0.16.0/checksums.txt "miactl checksums" [`bash-completion`]: https://github.com/scop/bash-completion "Programmable completion functions for bash" [`oh-my-zsh`]: https://ohmyz.sh "Oh My Zsh is a delightful, open source, community-driven framework for managing your Zsh configuration" diff --git a/docs/cli/miactl/30_commands.md b/docs/cli/miactl/30_commands.md index 910628e789..1a8a75f99a 100644 --- a/docs/cli/miactl/30_commands.md +++ b/docs/cli/miactl/30_commands.md @@ -441,6 +441,63 @@ Available flags for the command: - `--context`, to specify a different context from the currently selected one - `--company-id`, to set the ID of the desired Company +### rules + +Rules command helps you manage different rules for configuration update for the whole Company or specific Projects. + +:::tip +This feature is currently in closed preview and may be subject to breaking changes, reach out to your Mia-Platform referent +if you are interested in use it. +::: + +#### list + +List available rules for the Company or for a specific Project. + +Usage: + +```sh +miactl company rules list [flags] +``` + +Available flags for the command: + +- `--company-id`, the id of the Company +- `--project-id`, the id of the Project (if provided the command will print available rules for the project, + together with the rules inherited from the Company) + +#### update + +Helps you update rules for a Company or for a specific Project + +Usage: + +```sh +miactl company rules update [flags] +``` + +Available flags for the command: + +- `--company-id`, the id of the Company +- `--project-id`, the id of the Project (if provided the command will update the rules for the specified Project only) +- `-f`, path to the file where the rules are saved + +
+File example + +```json +[ + { + "roleIds": ["developer"], + "disallowedRuleSet": [ + {"ruleId": "endpoint.security.edit"} + ] + } +] +``` + +
+ ## project This command allows you to manage `miactl` Projects. diff --git a/docs/cli/miactl/40_examples.md b/docs/cli/miactl/40_examples.md index c7c7148845..0775e509fd 100644 --- a/docs/cli/miactl/40_examples.md +++ b/docs/cli/miactl/40_examples.md @@ -133,7 +133,7 @@ Finally, you can group the commands above and run them inside a pipeline, e.g. a # Insert that after your pipeline stages delivery: stage: deploy - image: ghcr.io/mia-platform/miactl:v0.15.0 + image: ghcr.io/mia-platform/miactl:v0.16.0 script: - miactl version diff --git a/docs/cli/miactl/changelog.md b/docs/cli/miactl/changelog.md index f196fa1699..9e9333b1b2 100644 --- a/docs/cli/miactl/changelog.md +++ b/docs/cli/miactl/changelog.md @@ -15,6 +15,18 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [v0.16.0] - 2024-11-21 + +### Added + +- `company rules list` command +- `company rules update` command + +### Changed + +- update go version to 1.23.2 +- update text to v0.19.0 + ## [v0.15.0] - 2024-09-12 ### Added @@ -307,7 +319,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - create cli sdk - create cli renderer -[unreleased]: https://github.com/mia-platform/miactl/compare/v0.15.0...HEAD +[unreleased]: https://github.com/mia-platform/miactl/compare/v0.16.0...HEAD +[v0.16.0]: https://github.com/mia-platform/miactl/compare/v0.15.0...v0.16.0 [v0.15.0]: https://github.com/mia-platform/miactl/compare/v0.14.0...v0.15.0 [v0.14.0]: https://github.com/mia-platform/miactl/compare/v0.13.0...v0.14.0 [v0.13.0]: https://github.com/mia-platform/miactl/compare/v0.12.2...v0.13.0 diff --git a/docs/console/company-configuration/clusters-management/cluster-setup.mdx b/docs/console/company-configuration/clusters-management/cluster-setup.mdx index ff31e54226..3b7d586063 100644 --- a/docs/console/company-configuration/clusters-management/cluster-setup.mdx +++ b/docs/console/company-configuration/clusters-management/cluster-setup.mdx @@ -36,7 +36,8 @@ You can choose between the automatic procedure and the manual one. ### ClusterRole - Next, we must define the roles needed by the previously created service account. These are the minimal roles required by the Console to work. + Next, make sure to define the roles needed by the previously created service account. + These are the minimal roles required by the Console to work. Here is the template to quickly define them: @@ -158,9 +159,34 @@ You can choose between the automatic procedure and the manual one. - {{NAME_OF_THE_SERVICE_ACCOUNT_USED_FOR_THE_DEPLOY}} ``` + #### Monitoring custom resources from the Console + + Follow these guidelines to configure the custom resources. + You need to make sure that the Console has the correct permissions + to display the information to the users. + + Here is an example to show how to give the correct permissions to custom resource definitions: + + ```yaml + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + # ... + rules: + # For each custom resource definitions we need to add: + - apiGroups: + - "" + resources: + - "" + verbs: + - get + - list + ``` + + After adding the necessary permissions follow this [guide](/console/design-your-projects/custom-resources/custom-resources.md) to see your custom resources in the Console. + ### ClusterRoleBindings - Finally, we **must** associate the roles with the service account using the `ClusterRoleBindings` that can be created using the following template: + Finally, make sure to associate the roles with the service account using the `ClusterRoleBindings` that can be created using the following template: ```yaml apiVersion: rbac.authorization.k8s.io/v1 diff --git a/docs/console/company-configuration/events.mdx b/docs/console/company-configuration/events.mdx index 5e4b075da8..028e64cb26 100644 --- a/docs/console/company-configuration/events.mdx +++ b/docs/console/company-configuration/events.mdx @@ -19,7 +19,6 @@ All the events triggered by the Console share some common properties: | `eventTimestamp` | `number` | The timestamp of the event emission | | `payload` | `object` | Contains the event-specific payload | - ## Event types Below are explained the events that can be triggered by the Console. @@ -101,9 +100,7 @@ This event will be triggered when a Project is created successfully. :::caution - The following schema is potentially non-exhaustive and may not cover all the possible properties of a Project resource. - ::: ```json @@ -461,6 +458,91 @@ hence there is no guarantee that the service will be found in the Project config +### Configuration saved + +This event will be triggered when the Project configuration is [successfully saved from Console Design section](/development_suite/api-console/api-design/overview.md#how-to-save-your-configuration). + + + + +| Property | Value | Description | +| -------------------- | -------- | ---------------------------------------------------------------------- | +| `tenantId` | `string` | The identifier of the Company the service belongs to | +| `projectId` | `string` | The identifier of the Project the service belongs to | +| `revisionName`  | `string` | The name of the saved revision (branch when using the standard workflow) | +| `savedChangesId`  | `string` | The changes id (commit for project using the standard workflow) used to register the saved configuration | +| `previousChangesId`  | `string` | The changes id (commit for project using the standard workflow) the current save started from | +| `startRef`  | `object` | Provided when saving on a new revision/branch | +| `startRef.name`  | `string` | Name of the original revision/branch/version/tag | +| `startRef.type`  | `string` | Type of the original ref used to start the current save, can be revision/version or branch/tag based on the used workflow | +| `author`  | `object` | Contains information about the save author | +| `author.id`  | `string` | Contains the id of the user performing the save | +| `author.name`  | `string` | Contains the name of the user performing the save | + + + + +```json +{ + "eventName": "tag_created", + "eventTimestamp": 123456, + "payload": { + "tenantId": "my-company-id", + "projectId": "0000000000000001", + "revisionName": "main", + "savedChangesId": "the-current-commit-id", + "previousChangesId": "the-previous-commit-id", + "author": { + "id": "the-user-id", + "name": "John Smith" + } + } +} +``` + + + + +```json +{ + "type": "object", + "required": ["eventName", "eventTimestamp", "payload"], + "additionalProperties": false, + "properties": { + "eventName": {"const": "configuration_saved", "type": "string"}, + "eventTimestamp": {"type": "number"}, + "payload": { + "type": "object", + "properties": { + "tenantId": {"type": "string"}, + "projectId": {"type": "string"}, + "revisionName": {"type": "string"}, + "savedChangesId": {"type": "string"}, + "previousChangesId": {"type": "string"}, + "startRef": { + "type":"object", + "properties": { + "name": {"type": "string"}, + "type": {"type": "string"} + } + }, + "author": { + "type": "object", + "properties": { + "id": {"type":"string"}, + "name": {"type":"string", "x-confidential": true} + } + } + } + } + } +} +``` + + + + + ### Tag or Version Created This event will be triggered when [a Project is successfully tagged from Console](/development_suite/api-console/api-design/overview.md#create-tag). @@ -539,167 +621,166 @@ In an Enhanced Workflow project, this event will be triggered when a version is -:::caution +:::caution The following schema is potentially non-exhaustive and may not cover all the possible properties of a Project resource. - ::: ```json { - "description": "The Project metadata (ideally, the whole Project resource)", - "type": "object", - "properties": { - "_id": { - "type": "string" - }, - "availableNamespaces": { - "type": "array", - "default": [], - "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - }, - "label": { - "type": "string" - } + "description": "The Project metadata (ideally, the whole Project resource)", + "type": "object", + "properties": { + "_id": { + "type": "string" + }, + "availableNamespaces": { + "type": "array", + "default": [], + "items": { + "type": "object", + "properties": { + "value": { + "type": "string" }, - "required": [ - "value" - ] - } - }, - "configurationGitPath": { - "type": "string" - }, - "defaultBranch": { - "type": "string" - }, - "description": { - "type": "string" - }, - "environments": { - "type": "array", - "default": [], - "items": { - "type": "object", - "properties": { - "label": { - "type": "string" - }, - "envId": { - "type": "string" - }, - "envPrefix": { - "type": "string" - }, - "hosts": { - "type": "array", - "items": { - "type": "object", - "properties": { - "host": { - "type": "string" - }, - "isBackoffice": { - "type": "boolean" - }, - "scheme": { - "type": "string", - "description": "an url schema, usually one of 'http' or 'https'" - } - } - } - }, - "description": { - "type": "string" - }, - "isProduction": { - "type": "boolean", - "default": false - }, - "cluster": { + "label": { + "type": "string" + } + }, + "required": [ + "value" + ] + } + }, + "configurationGitPath": { + "type": "string" + }, + "defaultBranch": { + "type": "string" + }, + "description": { + "type": "string" + }, + "environments": { + "type": "array", + "default": [], + "items": { + "type": "object", + "properties": { + "label": { + "type": "string" + }, + "envId": { + "type": "string" + }, + "envPrefix": { + "type": "string" + }, + "hosts": { + "type": "array", + "items": { "type": "object", "properties": { - "namespace": { + "host": { "type": "string" }, - "clusterId": { - "type": "string" - } - } - }, - "deploy": { - "type": "object", - "required": [ - "type" - ], - "properties": { - "type": { - "type": "string" + "isBackoffice": { + "type": "boolean" + }, + "scheme": { + "type": "string", + "description": "an url schema, usually one of 'http' or 'https'" } } } }, - "required": [ - "envId" - ] - } - }, - "name": { - "type": "string" - }, - "projectId": { - "type": "string" - }, - "repository": { - "type": "object", - "properties": { - "type": { + "description": { "type": "string" }, - "providerId": { - "type": "string" + "isProduction": { + "type": "boolean", + "default": false + }, + "cluster": { + "type": "object", + "properties": { + "namespace": { + "type": "string" + }, + "clusterId": { + "type": "string" + } + } + }, + "deploy": { + "type": "object", + "required": [ + "type" + ], + "properties": { + "type": { + "type": "string" + } + } } - } - }, - "repositoryUrl": { - "type": "string" - }, - "tenantId": { - "type": "string" - }, - "imagePullSecretNames": { - "type": "array", - "items": { + }, + "required": [ + "envId" + ] + } + }, + "name": { + "type": "string" + }, + "projectId": { + "type": "string" + }, + "repository": { + "type": "object", + "properties": { + "type": { "type": "string" - } - }, - "monitoring": { - "type": "object", - "properties": { - "systems": { - "type": "array", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string" - } - }, - "required": ["type"] - } - } }, - "required": ["systems"] - }, - "containerRegistries": { - "type": "array" + "providerId": { + "type": "string" + } + } + }, + "repositoryUrl": { + "type": "string" + }, + "tenantId": { + "type": "string" + }, + "imagePullSecretNames": { + "type": "array", + "items": { + "type": "string" } + }, + "monitoring": { + "type": "object", + "properties": { + "systems": { + "type": "array", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string" + } + }, + "required": ["type"] + } + } + }, + "required": ["systems"] + }, + "containerRegistries": { + "type": "array" } } +} ``` diff --git a/docs/console/company-configuration/providers/configure-marketplace-provider.mdx b/docs/console/company-configuration/providers/configure-marketplace-provider.mdx index 2a0f17024b..25c5576425 100644 --- a/docs/console/company-configuration/providers/configure-marketplace-provider.mdx +++ b/docs/console/company-configuration/providers/configure-marketplace-provider.mdx @@ -7,7 +7,7 @@ sidebar_label: Manage Marketplace Providers When adding a new Provider connection, you can choose to define it as a "**Marketplace**" Provider. By doing so, you can decide to make any resources related to that specific **Provider** available to other Companies. -For more information about how to share a Marketplace Resource, please refer to the [dedicated documentation page](/marketplace/add_to_marketplace/marketplace_items_accessibility.md). +For more information about how to share a Marketplace Resource, please refer to the [dedicated documentation page](/software-catalog/catalog-and-marketplace/overview.md). :::info diff --git a/docs/console/design-your-projects/custom-resources/custom-resources.md b/docs/console/design-your-projects/custom-resources/custom-resources.md index 38f41e8221..783171f865 100644 --- a/docs/console/design-your-projects/custom-resources/custom-resources.md +++ b/docs/console/design-your-projects/custom-resources/custom-resources.md @@ -8,6 +8,10 @@ A Infrastructure Resource allows you to define custom objects that are not part An Infrastructure resource may be either Kubernetes type, and thus refer to a particular Custom Kubernetes Resource, or to Non-Kubernetes ones (Lambda functions, Terraform resources, etc.). +:::info +In order to visualize your custom resources in the monitoring area, you must give permissions to the console service account. Please follow the guide found [here](/console/company-configuration/clusters-management/cluster-setup.mdx?type=manual#monitoring-custom-resources-from-the-console) +::: + ## How to use the Infrastructure Resource With Infrastructure Resources it is possible to: @@ -49,7 +53,7 @@ In creation, you will see the preview of the generated manifest. #### Create an Infrastructure Resource from Marketplace :::info -To allow users to add a Infrastructure Resource to their project from marketplace, you need to apply it using `miactl` ([see here for details](/marketplace/add_to_marketplace/add_item_by_type/add_custom_resource.md)). +To allow users to add a Infrastructure Resource to their project from marketplace, you need to apply it using `miactl` ([see here for details](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_infrastructure_resource.md)). ::: To create a resource from Marketplace, you need to select the Infrastructure Resource you want to create. @@ -125,7 +129,7 @@ Users with appropriate permissions can manage the lifecycle of a Infrastructure Infrastructure Resources are published to the Marketplace using the `custom-resource` type in the marketplace item schema. Versioning is supported, allowing users to make updates without overwriting previous versions of the Infrastructure Resource. -To learn more on how to add or manage a Infrastructure Resource in the Marketplace, see the [Add Custom Resource to the Marketplace](/marketplace/add_to_marketplace/add_item_by_type/add_custom_resource.md) section. +To learn more on how to add or manage a Infrastructure Resource in the Marketplace, see the [Add Custom Resource to the Marketplace](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_infrastructure_resource.md) section. ### Template-based Infrastructure Resource management diff --git a/docs/console/design-your-projects/sidecars.md b/docs/console/design-your-projects/sidecars.md index 07d0259f35..17cfe8ec9d 100644 --- a/docs/console/design-your-projects/sidecars.md +++ b/docs/console/design-your-projects/sidecars.md @@ -54,7 +54,7 @@ If you want to create a new instance of a sidecar you are already using in some :::tip It is possible to define and publish sidecar resource definitions on the Marketplace. -Find out more in the [Publish your sidecar to the Marketplace](/marketplace/add_to_marketplace/add_item_by_type/add_sidecar.md) guide. +Find out more in the [Publish your sidecar to the Marketplace](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_sidecar.md) guide. ::: #### Clone a sidecar diff --git a/docs/console/project-configuration/kustomize-your-configurations/kustomize-use-cases.md b/docs/console/project-configuration/kustomize-your-configurations/kustomize-use-cases.md index 001d953ab5..ea4bd4782e 100644 --- a/docs/console/project-configuration/kustomize-your-configurations/kustomize-use-cases.md +++ b/docs/console/project-configuration/kustomize-your-configurations/kustomize-use-cases.md @@ -160,7 +160,7 @@ patches: With the example above, the `istio-proxy` container will be added to deployments with **all the specified labels and annotations**. :::info -You can apply labels to microservices inside the Design section of the Mia-Platform Console, or, in case of Self-Hosted installation, you can [set default labels](/marketplace/add_to_marketplace/add_item_by_type/add_plugin.md#properties-of-plugin-resources) to the microservices created from Marketplace. +You can apply labels to microservices inside the Design section of the Mia-Platform Console, or, in case of Self-Hosted installation, you can [set default labels](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_plugin.md#properties-of-plugin-resources) to the microservices created from Marketplace. ::: ### Enable **High Availability** for business critical microservices diff --git a/docs/development_suite/api-console/api-design/fine-grained-access-control.md b/docs/development_suite/api-console/api-design/fine-grained-access-control.md new file mode 100644 index 0000000000..256280d70e --- /dev/null +++ b/docs/development_suite/api-console/api-design/fine-grained-access-control.md @@ -0,0 +1,236 @@ +--- +id: fine-grained-access-control +title: Fine-Grained Access Control in Design +sidebar_label: Fine-Grained Access Control +--- + +# Fine-Grained Access Control in Design + +:::info +This feature is currently available exclusively as a **Closed Preview** and is not yet generally available. For more information and to request its activation for your Company, please contact your Mia-Platform referent. +::: + +This feature introduces a mechanism for managing user interactions within the application by restricting specific actions based on user roles and specified rules in the Design section. + +If a user attempts to save a configuration after performing some changes that are forbidden by the configured rules, the saving is blocked and an error is returned. + +*Rules* and *user roles* can be configured at both the Project and the Company levels. +The following logic is applied: + +- **Rules**: Project and Company rules are combined together without conflict, as only disallow rules are used. +- **User Roles**: If a user has roles assigned at the Project level, only those roles used to find the applicable rules. If no Project-level roles are assigned, the roles defined at the Company level are used instead. + +## Configuration definition + +To enable this feature the `Project` or `Company` `configurationManagement.saveChangesRules` field of the configuration must be set with a list of objects with the following structure: + +| Field | Type | Description | Optional | +| ------------------- | ----------- | --------------------------------------------- | -------- | +| `disallowedRuleSet` | `RuleSet[]` | list of rules that prohibit a specific action | ❌ | +| `roleIds` | `String[]` | List of user roles to which the rules apply | ❌ | + +The `RuleSet` object has these fields: + +| Field | Type | Description | Optional | +| ------------------- | ------------------ | --------------------------------------------------------------- | -------- | +| `jsonPath` | `String` | JSONPath of the resource on which the action must be prevented. | ✅ | +| `processingOptions` | `ProcessingOption` | Additional options of the rule | ✅ | +| `ruleId` | `String` | Reference a to a rule from a predefined set | ✅ | + +___ +A `disallowedRuleSet` can be configured in 3 ways: + +- [Via `jsonPath`](#via-jsonpath) +- [Via `jsonPath` and `processingOptions`](#via-jsonpath-and-processingoptions) +- [Via `ruleId`](#via-ruleid) + +### Via `jsonPath` + +The `jsonPath` field is used to extract a target resource applying a JSONPath expression on the JSON structure of the configuration. On the extracted resource are not permitted any updates. + +### Via `jsonPath` and `processingOptions` + +- The `jsonPath` is used to extract the target resource. +- The `processingOptions` define the `action` (`create`, `delete`) to prevent on the resource. If the resource captured by the jsonPath are of array type, the field `primaryKey` must be specified. + +The `ProcessingOption` object has the following structure: + +| Field | Type | Description | Optional | +| ------------ | ---------- | ---------------------------------------------------------------------------------------------------- | -------- | +| `action` | `string[]` | Action to be prevented on the resource defined via the jsonPath. Possible values: `create`, `delete` | ❌ | +| `primaryKey` | `String` | Primary key of the resource captured by the jsonPath. Mandatory if resource is of array type | ✅ | + +### Via `ruleId` + +The `ruleId` references a rule from a predefined set of rules, that define a specific behavior. + +**The available `ruleIds` are**: + +| `ruleId` | Description | +| ------------------------- | --------------------------------------------------------------------------------------------------- | +| `endpoints.security.edit` | block edit of the fields [`public`, `acl`, `secreted`] of `endpoints` and `routes` inside endpoints | +| | | + +## Fetching and configuring rules with `miactl` + +:::tip +The following commands are available from [miactl v0.16.0](https://github.com/mia-platform/miactl/releases/tag/v0.16.0), make sure you upgrade. + +For the full command specification, please refer to the [related miactl documentation](/cli/miactl/30_commands.md#rules). +::: + +Command examples: + +```bash +miactl company rules list --company-id=my-company +miactl company rules list --company-id=my-company --project-id=my-project +miactl company rules update --company-id=my-company -f ~/my-rules.json +miactl company rules update --company-id=my-company --project-id=my-project -f ~/my-rules.json +``` + +Example for the file `my-rules.json`: + +```json +[ + { + "roleIds": ["developer"], + "disallowedRuleSet": [ + {"ruleId": "endpoint.security.edit"} + ] + } +] +``` + +## Configuring rules via API + +### Updating rules on a Project + +The API for updating the rules on a Project is defined as follows + +:::caution +This API is meant for internal use and will be subject to breaking changes. +::: + +#### Request + +- verb: `PATCH` +- path: `/api/backend/projects/:projectId/rules` + +##### Security + +| Security | Check | +|-------------------------|---------------------------------| +| Authentication required | ✅ | +| RBAC permissions | console.company.details.update | + +##### Body + +The **body** of the request has the structure described in [Configuration definition](#configuration-definition) + +### Updating rules on a Company + +The API for updating the rules on a Company is defined as follows. + +:::caution +This API is meant for internal use and will be subject to breaking changes. +::: + +#### Request + +- verb: `PATCH` +- path: `/api/backend/tenants/:tenantId/rules` + +##### Security + +| Security | Check | +|-------------------------|---------------------------------| +| Authentication required | ✅ | +| RBAC permissions | console.company.details.update | + +##### Body + +The **body** of the request the structure described in [Configuration definition](#configuration-definition) + +Below are some **examples of request bodies** for the Update Rules API. The request body format is identical for both the Update Project and Update Company APIs. + +- prevent edit of the `dockerImage` of all services to the role `maintainer` + +```json + { + "configurationManagement": { + "saveChangesRules": [ + { + "disallowedRuleSet": [ + { + "jsonPath": "$.services.*.dockerImage" + }, + ], + "roleIds": [ + "maintainer" + ] + } + ] + } + } +``` + +- prevent creation of the resource `secrets` to the role `maintainer` + +```json +{ + "configurationManagement": { + "saveChangesRules": [ + { + "disallowedRuleSet": [ + { + "jsonPath": "$.collections", + "processingOptions": { + "action": "create" + } + } + ], + "roleIds": ["maintainer"] + } + ] + } +} +``` + +- prevent the creation of a services of a specific type (`custom-resource`) to the role `maintainer` + +```json +{ + "configurationManagement": { + "saveChangesRules": [ + { + "disallowedRuleSet": [ + { + "jsonPath": "$.services.[?(@.type==\"cursom-resource\")]", + "processingOptions": { "action": "create" } + } + ], + "roleIds": ["maintainer"] + } + ] + } +} +``` + +- configure the predefined rule with `ruleId` "endpoints.security.edit" to the role `maintainer` + +```json +{ + "configurationManagement": { + "saveChangesRules": [ + { + "disallowedRuleSet": [ + { + "ruleId": "endpoints.security.edit" + } + ], + "roleIds": ["maintainer"] + } + ] + } +} +``` diff --git a/docs/development_suite/monitoring/resources/custom-resources.md b/docs/development_suite/monitoring/resources/custom-resources.md index 07dd767d14..d7b007898d 100644 --- a/docs/development_suite/monitoring/resources/custom-resources.md +++ b/docs/development_suite/monitoring/resources/custom-resources.md @@ -11,7 +11,7 @@ If deployed, the information on the [Custom Resources](/console/design-your-proj :::caution If you created one or more Custom Kubernetes Resource from a marketplace template **prior** to Console release v13.3.0, the resources **will not be visible by default**. -Please ensure to [update your resource](/marketplace/add_to_marketplace/add_item_by_type/add_custom_resource.md#update-a-custom-resource-to-the-console-v1330) version via [miactl](/cli/miactl/10_overview.md) to one that has the properties `resourceId` and `type` correctly set in the `runtime` object field of its definition, otherwise the Custom Kubernetes Resources won't be visible in the section even if the resource is active. +Please ensure to [update your resource](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_infrastructure_resource.md#update-a-custom-resource-to-the-console-v1330) version via [miactl](/cli/miactl/10_overview.md) to one that has the properties `resourceId` and `type` correctly set in the `runtime` object field of its definition, otherwise the Custom Kubernetes Resources won't be visible in the section even if the resource is active. ::: diff --git a/docs/getting-started/faqs.md b/docs/getting-started/faqs.md index 2ed32e81e4..9037286f0a 100644 --- a/docs/getting-started/faqs.md +++ b/docs/getting-started/faqs.md @@ -35,10 +35,6 @@ This should list the expected routes under each category in the API Portal. When both are used, the global rate limits set by the plugin are applied first, followed by the endpoint-specific limits. -### [Rate Limiting for Sub-Routes in Envoy](https://github.com/mia-platform/community/discussions/526) -#### Can I specify rate limits for sub-routes in Envoy using the Console? -This is a limitation of the Console, not Envoy. Currently, the Console does not support setting rate limits for sub-routes directly. As a workaround, you can create separate endpoints (e.g., /basepath/hello-1) and apply rate limits to those. While this approach might be cumbersome for projects with many endpoints, it should work for now until more granular control is available in the Console. - ### [Retrieving Name and Surname in Users CRUD with Okta Authentication Service](https://github.com/mia-platform/community/discussions/512) #### Why are the name and surname fields empty in the users CRUD after setting up the Authentication Service with Okta? The issue likely arises from not having the correct scopes set in your Okta configuration. Ensure that you include the profile scope, which is needed to retrieve basic user information, including the name. @@ -320,7 +316,7 @@ No, it's not mandatory. However, starting from a [Mia-Platform Template](/market ### Can I create my own templates? #### How can I create custom templates for my microservices? -Yes, you can. Follow this [guideline](/marketplace/add_to_marketplace/create_your_company_marketplace.md) and [open an issue with the Marketplace contribution template](https://github.com/mia-platform/community/issues/new?labels=marketplace&template=marketplace-contribution.md&title=Add+new+marketplace+item). +Yes, you can. Follow this [guideline](/software-catalog/manage-items/overview.md) and [open an issue with the Marketplace contribution template](https://github.com/mia-platform/community/issues/new?labels=marketplace&template=marketplace-contribution.md&title=Add+new+marketplace+item). ### How can I change the state of a document? #### What is the process to change the state of a document in CRUD? diff --git a/docs/marketplace/add_to_marketplace/change_marketplace_item_visibility.md b/docs/marketplace/add_to_marketplace/change_marketplace_item_visibility.md deleted file mode 100644 index 9d833edf1e..0000000000 --- a/docs/marketplace/add_to_marketplace/change_marketplace_item_visibility.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -id: change_marketplace_item_visibility -title: Change Marketplace Items Visibility -sidebar_label: Change Marketplace Items Visibility ---- - -The Marketplace is an essential tool within the Development Platform, designed to empower developers with maximum autonomy in their development activities. As such, it offers a vast library of ready-to-use components that are highly dynamic. Consequently, there may arise a need for an item that initially started as a public asset within the Marketplace to be restricted for use by a single Company. In the opposite scenario, an item that began as private for exclusive use by one Company may need to become publicly available to all Companies. - -This guide aims to assist the reader in transforming Marketplace items concerning their visibility within Companies: from public to private, or vice versa, from private to public. - -:::info - -To create a Marketplace item, please follow [this](/marketplace/add_to_marketplace/create_your_company_marketplace.md) dedicated guide. - -::: - -### Porting an existing item to the Private Marketplace - -In the event that you need to port an item originally available in the public Marketplace to the private Marketplace, the first step is to communicate this intention to Mia-Platform maintenance team through a [Service Request](https://makeitapp.atlassian.net/servicedesk/customer/portal/21) or via a [GitHub Discussion](https://github.com/mia-platform/community). - -Once the Mia-Platform team receives the request and assesses its feasibility, they will grant authorization to proceed with the porting and monitor migration activities. After obtaining the authorization to proceed with the porting, you will need to create a repository on your Git Provider and migrate the code of the item you want to transfer. During this phase, if necessary, you will also need to configure your CI/CD pipelines. - -Once the repository configuration is complete, the final operational step involves creating the Item Configuration following the [guide for creating Marketplace items](/marketplace/add_to_marketplace/create_your_company_marketplace.md). At this point, it's essential to notify the Mia-Platform maintenance team of the completion of the preceding steps, either through the previously opened service request or GitHub discussion. This will allow them to proceed with the removal of the old item and its related configurations (repositories, pipelines, etc.) from the publicly accessible Marketplace. - -## Porting an existing item to the Public Marketplace - -For porting a Marketplace item from public to private, the procedure is very similar to the one previously discussed for porting an item from public to private. In this case, the first step is to create the new item in the public Marketplace, following the procedure to make your Marketplace item available to other companies as well. - -Once this procedure is completed, and the item is effectively available on the public Marketplace, you can proceed with retiring the private item. This involves removing the Item Configuration and its related configurations such as repositories and pipelines. - -:::caution - -The repositories and pipelines should only be deleted if they have not been reused in defining the new item in the public Marketplace. - -::: - diff --git a/docs/marketplace/add_to_marketplace/create_your_company_marketplace.md b/docs/marketplace/add_to_marketplace/create_your_company_marketplace.md deleted file mode 100644 index c1a8e040cd..0000000000 --- a/docs/marketplace/add_to_marketplace/create_your_company_marketplace.md +++ /dev/null @@ -1,221 +0,0 @@ ---- -id: create_your_company_marketplace -title: Create your Company Marketplace -sidebar_label: Company Marketplace ---- - -In this section, we dive into the process of creating a new item for your **Company Marketplace**, analyzing the main differences between different types of items and providing some configuration examples. - -## Public and Company Marketplace - -As a Console user, you can access both Mia-Platform public Marketplace catalog and your Company Marketplace. -While the Mia-Platform public Marketplace is composed by all the items publicly available in the Mia-platform catalog, the **Company Marketplace** is a Company-specific private space where to create and manage the items which are available only for your Company. - -The **Mia-Platform public Marketplace** is the place where every Company can find most of the items needed to set up its Project architecture. It is publicly available on Mia-Platform Console, meaning that all Companies can view and make use of its items. - -However, a Company might want to have its own internal Marketplace, fulfilled also with items that must not be shared with everyone else outside the Company. - -:::info -There are different methods to manage your Company Marketplace items. They are described in details in the [related page](/marketplace/add_to_marketplace/manage_marketplace_items.md) -::: - -## Creation of an Company Marketplace item - -Creation of a Marketplace item for your Company consists of two steps. The first is writing a Marketplace Item configuration file, then you have to upload it to the Console by using [`miactl`](/cli/miactl/10_overview.md), the official Mia-Platform CLI tool. - -:::info -If you want to make your Marketplace item accessible to other Companies, you can visit [this page](/marketplace/add_to_marketplace/marketplace_items_accessibility.md). - -Also, to learn how to migrate an item from the public to private internal Marketplace and vice versa, please refer to the [dedicated page](/marketplace/add_to_marketplace/change_marketplace_item_visibility.md). -::: - -### Marketplace item visibility and the `tenantId` field - -When creating a new Marketplace item, you always need to set the `tenantId` related to the Company you are creating the item in. - -You can also contribute to the **Mia-Platform Marketplace** by making your Marketplace item accessible to other Companies: visit [this page](/marketplace/add_to_marketplace/marketplace_items_accessibility.md) for further information on this point. - -:::caution -Not setting the `tenantId` is no longer supported and deprecated. -Elements without `tenantId` will be public even if the `visibility.public` field is not set. - -This behavior might change in the next Console releases. - -If you have any item without the `tenantId` property set, we recommend to do the following: - -- set the `tenantId` to any of your companies; -- set the `visibility` field according to your needs. See the [related doc](/marketplace/add_to_marketplace/marketplace_items_accessibility.md#marketplace-item-visibility) for more information on this point. - -::: - -## Marketplace items - -A Marketplace **Item** (also referred to as **Component**) is the basic unit of the Marketplace and represents a software resource available for use within Mia-Platform Projects. - -These components provide various functionalities and can be integrated into Mia-Platform Projects to streamline development and configuration processes. - -The Mia-Platform Marketplace contains items belonging to many types, with different use cases. - -To use a Marketplace item in a Project, a user have to **create** it; depending on the type, the creation of an element has different consequences on the Project. - -### Item Types - -The Marketplace is composed of items with the following types. - -- **Plugins**: items for which users have no access to the actual code. Users will still be able to download their Docker image, in order to configure and use them within their Projects. -- **Templates** and **Examples**: archives for which a new repository is generated. The developer will have direct access to the new repository (created in their Project scope) and will be able to evolve its code at will. A template is a repository that, net of the development environment and framework setup, is empty; an example, instead, also implements some features tailored to help the user better familiarize with the development environment. -- **Applications**: bundles of resources that can be created and configured in the Mia-Platform Console within a few clicks. [Applications](/marketplace/applications/mia_applications.md) are composed of microservices (Plugins, Examples, and Templates), endpoints, CRUD collections, and public variables. Users can monitor if all the resources composing an application have been correctly set up inside the project, as well as access their corresponding repository or configuration. -- **Proxies**: specific configurations used to invoke APIs that are not part of the current project but may be exposed by an external provider or another project. You can find more information about proxies in [this section](/development_suite/api-console/api-design/proxy.md). -- **Sidecars**: secondary utility containers running side by side with the main container in the same host. Find more [here](/marketplace/add_to_marketplace/add_item_by_type/add_sidecar.md) -- **Custom Resources**: custom objects that are not part of the standard Console supported resources. For more information, go to [this section](/marketplace/add_to_marketplace/add_item_by_type/add_custom_resource.md) - -:::note -Marketplace items are identified by a **Category** (e.g. Data Stream, Data Visualization, Insurance, Healthcare... ). -::: - -## How to configure a new item - -In the following section we'll explore the common fields shared by all marketplace item types. - -Refer to the [detailed explanation by type](#marketplace-items-example-and-explanation) for the type-specific fields and examples of working JSON marketplace items entities. - -Here below are listed all the properties that must be provided for each type of item: - -The service documentation of your plugin will be accessible from a specific link in the Marketplace, you also need to provide the documentation URL of your plugin and this must be inserted in the `documentation` field: - -- **`name`** (required): the item name appearing in the Marketplace card -- **`tenantId`** (required): the ID of the Company the item belongs to -- **`itemId`** (required): the ID identifying the item in the Marketplace -- **`description`**: a brief description (10 to 20 words) regarding the service functionalities -- **`type`**: the type of your item (plugin, template, example, application, or proxy) -- **`documentation`**: information about the documentation of your item. It is an object composed by: - - **`type`**: the type of documentation. It can be `externalLink` or `markdown` - - **`url`**: the URL of the documentation. It can be an external URL or an internal one -- **`comingSoon`** and **`releaseStage`**: properties to identify the maturity of the item (learn how to configure them in a [dedicated section](/marketplace/add_to_marketplace/create_your_company_marketplace.md#the-release-stage-of-a-new-item) later on this page) -- **`categoryId`**: a label to help categorize items by their purpose or use case. As specified before, categories are only created internally at Mia-Platform. The `categoryId` of a item uniquely specifies both the specific category and sub-category (e.g. Start from Code (category) - Node.js (subcategory) will be identified by the `categoryId` "nodejs"). The [available category IDs](/marketplace/add_to_marketplace/create_your_company_marketplace.md#category-list) are listed below. -- **`supportedBy`**: a label to identify the company that has produced the item (only used if `supportedByImage` is not provided) -- **`imageUrl`** and **`supportedByImageUrl`**: respectively the image that will be associated with the item and the image that will be associated with the company that has produced it. -- **`version`**: the version of the item. It is an object composed by the following properties: - - **`name`** (required): the actual version of the item. We suggest to use the [Semantic Versioning](https://semver.org/) format. - - **`releaseNote`**: a release note that will be displayed to the user when selecting the item during creation or updates based on Marketplace items in a Console project; includes information about the changes introduced by the new version. - - **`security`**: a boolean to indicate if the item is security-related - -Each marketplace item is identified by the values of the **`tenantId`**, the **`itemId`** and the **`version`** name properties. So, when you need to create a new Marketplace item, be sure to provide unique values for these properties. - -:::info -To upload the *image* and *supportedByImage*, you can use the `miactl marketplace apply` command adding the respective `image` and `supportedByImage` keys to the object. - -Refer to the [related miactl documentation](/cli/miactl/30_commands.md#apply) to know the exact specifications of such object. -::: - -### Set controlled versions for your Marketplace resources and make them available to users - -:::info -This feature is currently available for the [Plugin](/marketplace/add_to_marketplace/add_item_by_type/add_plugin.md) and [Custom Resource](/marketplace/add_to_marketplace/add_item_by_type/add_custom_resource.md) types. -::: - -Marketplace creators have now the possibility to manage some types of resources (at the moment, Plugins and Custom Resources of type k8s) through a governance based on a versioning system. - -This means that, for these types of resources, it is possible to establish a more structured and transparent lifecycle management system, providing users access to all the versions of a resource and allowing them to see the release notes of each version and select and instantiate the version that best suits their configuration needs among the ones made available by the Marketplace creator. - -This versioning system also provides significant advantages in a feature-branch design workflow, effectively leveraging different versions of the same Marketplace item across various branches of a project. - -For instance, we imagine to have a project with three different revisions: *dev*, *stage* and *main*, with the latter being the branch with the official configuration. Let's also imagine to have installed in all the three revisions the *CRUD Service* plugin, which includes different versions. - -In this scenario we can have: - -- the `main` branch with the `6.6.0` version, which is the supported version in our project -- we can use the the version `6.10.0` in the `stage` branch where the latest manual tests and verifications are performed before to be included in the `main` branch -- at the same time we can experiment and test features using the version `7.0.0` in your `dev` branch without affecting the other branches and the existing configurations - -This approach facilitates a smooth upgrade process, enables thorough testing of new features, and ensures compatibility across different stages of your project lifecycle. This flexibility allows for testing new versions in development environments while maintaining stable versions in production. -Such a structured approach will streamline resource management and ensure compatibility and stability across different use cases. - -#### How to create a new version for your resource - -To create a versioned resource, you need to set a specific value for the `name` property of the `version` object to the resource definition, as explained in the ["How to configure a new item" section](#how-to-configure-a-new-item). - -Also, to provide continuity to the definition of the other versions of the same resource, the `tenantId` and the `itemId` properties must be the same for all the versions of the same resource. - -You can create a new version of a Marketplace item either if there is already that resource on the Marketplace without a version. In that case the non-versioned item will be still available in the Console, where will be shown with a *N/A* value for the version. - -If there are multiple version of the same item, one of these versions will be used as *latest version*. -This is the version that will be used as a reference when you will create a new microservice or a new resource choosing the item from the Marketplace. - -The latest version is going to be the one with the highest version, according to the [Semantic Versioning rules](https://semver.org/). -We suggest to follow these guidelines when assigning a version to your item, in order to easily determine which one is the latest. - - ![List of marketplace versions](./img/version_list.png) - -::: info -Also you will be informed if one or more of your resources attached to a Marketplace item have updates. - -You can find a list of all the updates at the bottom of the sidebar menu with the list of all your services, as well as inside the detail page of the service that can be updated. - - ![Design page with notifications of new Marketplace versions](./img/versions_notifications.png) -::: - -#### Editing a versioned resource - -Versioned resources are defined to be immutable, to avoid that updates might overwrite the previous configuration. However, it is possible to edit in case we need to update changes to their metadata (e.g. the release note or the description of the marketplace item - because of typos or other reasons). - -Editing a versioned resource is possible via `miactl`, however the following fields cannot be edited: - -- `itemId` -- `tenantId` -- the `name` property inside `version` object -- the `resources` property, that includes the specific resource definition - -Since marketplace items are defined by the `itemId`, the `tenantId` and the `version` name, attempt to modifying one of these three properties will cause the creation of a new marketplace item, completely separated from the previous one. - -Attemping to modify the `resources` property will cause an error, and the item will not be updated. In that case, you need to create a new version of the item. - -Also, the following fields are editable only in case the permission `marketplace.root.manage` has been granted to the user: - -- `supportedBy` -- `supportedByImage` -- `publishOnMiaDocumentation` -- `visibility` - -More information about these permissions are available in the [](/development_suite/identity-and-access-management/console-levels-and-permission-management.md#console-root-level-permissions) - -#### Version dependent properties - -Versioning of Marketplace resources implies that those resources under versioning governance are composed by some *dependent fields* that contribute to the definition of the version and which, therefore, cannot be changed “in place” by the user, but only through the creation of a new version of the resource. - -For instance: - -- a version of a Microservice Plugin is defined by its `dockerImage`. By following the resource versioning management, a change in this field will require the creation of a new version for such Plugin -- for Custom Resources of type K8s the governance is quite similar: since Custom Resources of type K8s are defined by their `apiVersion` and `kind`, in this scenario, the only way to be able to change them will be through the creation of a new version. - -By defining these fields as *version dependent*, we ensure that these are not editable by the user when they add a marketplace item to their project: whenever a new Microservice is created starting from a versioned Marketplace plugin, the `dockerImage` field will be automatically shown as read-only, and the user will be able to change it only by actually checking for other versions of the plugin. - -### The Release Stage of a Marketplace Item - -When creating or updating a Marketplace item, the user can add information to help users identifying the maturity of the item. - -There are 2 fields that define the release stage of an item: - -- the `comingSoon` field is boolean, setting it to true will show the *Coming Soon* label and will prevent users to use the item -- the `releaseStage` field can have the following values: - - *preview* - - *beta* - - *stable* (default) - - *deprecated* - a label will shown on the item according to the value of the field, except for the *stable* stage - -:::info -Setting both the `releaseStage` and the `comingSoon` fields is not permitted and would lead to inconsistencies; please set either field or none according to the item lifecycle status. -::: - -Refer to the [Items Lifecycle](/marketplace/overview_marketplace.md#marketplace-item-lifecycle) section for details about each specific release stage. - -## Marketplace Items example and explanation - -Refer to the detailed explanations and examples for each item type: - -- [Plugins](/marketplace/add_to_marketplace/add_item_by_type/add_plugin.md) -- [Templates and Examples](/marketplace/add_to_marketplace/add_item_by_type/add_template_or_example.md) -- [Applications](/marketplace/add_to_marketplace/add_item_by_type/add_application.md) -- [Sidecars](/marketplace/add_to_marketplace/add_item_by_type/add_sidecar.md) -- [Custom Resources](/marketplace/add_to_marketplace/add_item_by_type/add_custom_resource.md) diff --git a/docs/marketplace/add_to_marketplace/marketplace_items_accessibility.md b/docs/marketplace/add_to_marketplace/marketplace_items_accessibility.md deleted file mode 100644 index 4ab8053483..0000000000 --- a/docs/marketplace/add_to_marketplace/marketplace_items_accessibility.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -id: marketplace_items_accessibility -title: Make your Marketplace items available to other Companies -sidebar_label: Make your Marketplace items available to other Companies ---- - -## Enabling the visibility to all Companies - -* (recommended) Use the [CMS](/microfrontend-composer/previous-tools/cms/guide_cms.md) to make your Marketplace item accessible to other Companies. -* Open an issue on Mia-Platform [Github community page](https://github.com/mia-platform/community). - -Both methods will be explained in the following paragraphs. - -## Marketplace item visibility - -### Accessibility to other Companies - -To make a Marketplace item of your Company accessible to other Companies, you first need to create it. Follow the instructions on [this page](/marketplace/add_to_marketplace/create_your_company_marketplace.md#how-to-configure-a-new-item) to do so. - -When creating your Marketplace item, you can make it accessible to other companies by editing its `visibility` property. Specifically, set the `allTenants` property inside the `visibility` object to "true". -After editing, the visibility property should look like this: - -```json -... -"visibility": { - "allTenants": true -} -... -``` - -Depending on whether the item is hosted on a public or private repository, you may have to perform additional actions, as described here below. - -#### Open Source item - -If the repository where your Marketplace item is located is public and freely accessible (open source), then you have completed the process, and your marketplace item can now be accessed and used by other Companies! - -#### Item hosted on a private repository - -To allow the Console to access the private repository, you need to create a **Provider for Marketplace**, in which you will specify the credentials to access the Git Provider. Follow [these steps](/console/company-configuration/providers/configure-marketplace-provider.mdx) to learn how to create it. - -The Provider has to be created in the same Company where the item is created (defined in the property `companyId` of the item). - -:::info -Please note that, in order for the Marketplace resources to be visible to other Companies, yor need to enable the *Allow access to all the Companies* switch, as explained [here](/console/company-configuration/providers/configure-marketplace-provider.mdx#step-2-provider-details). -This allows the Console to access Marketplace items resources when they are created within a Project belonging to any Company. -::: - -After creating and connecting your Provider, locate it in the Providers section of the CMS and take note of the `providerId`; go back to the CMS and edit the Marketplace item that you want to publish, and set to it the property `providerId` with the value you copied from the provider. - -From this moment, your new Marketplace item should be available to any Company! - -### Public Visibility - -To make a Marketplace item accessible to the public, i.e. any user that access the Console, even if not authenticated, you can set the `visibility.public` field to `true`. The default value is `false`, meaning that an item will not be exposed to the public. - -:::caution -By default, for retrocompatibility reasons, Marketplace items without the `tenantId` are exposed to the public, regardless of the presence of the `visibility.public` field. - -Since v12.x.x, **the `tenantId` field is mandatory**; the upgrade script will take care of adding a default `tenantId` and `visibility.public: true` only to Mia-Platform supported Marketplace items. - -If you have any Marketplace item supported by you without a `tenantId`, **you have the responsibility to set a `tenantId`** to them. Failing to do so may result in errors in the next Console releases. Remember also to update their `visibility` according to your needs -::: diff --git a/docs/marketplace/examples/mia_examples.md b/docs/marketplace/examples/mia_examples.md index 4e738f41ed..2766d34a75 100644 --- a/docs/marketplace/examples/mia_examples.md +++ b/docs/marketplace/examples/mia_examples.md @@ -33,4 +33,4 @@ Mia-Platforms currently supports the following examples: Their code is open source, feel free to open a PR to contribute to any of them! -If you want to create your own example, head to the [Create your Company Marketplace](/marketplace/add_to_marketplace/create_your_company_marketplace.md) page for further information. +If you want to create your own example, head to the [Create your Company Marketplace](/software-catalog/manage-items/overview.md) page for further information. diff --git a/docs/marketplace/img/item-version.png b/docs/marketplace/img/item-version.png new file mode 100644 index 0000000000..665eb0c618 Binary files /dev/null and b/docs/marketplace/img/item-version.png differ diff --git a/docs/marketplace/overview_marketplace.md b/docs/marketplace/overview_marketplace.md index 3fb25dc666..641c6c6baa 100644 --- a/docs/marketplace/overview_marketplace.md +++ b/docs/marketplace/overview_marketplace.md @@ -8,7 +8,7 @@ The Mia-Platform Marketplace contains several code resources that facilitate a f In the Marketplace, you will be able to choose from a set of **items**, also called **components**, to easily set up a single microservice or a bundle of resources **with predefined and tested functionalities**. -The Marketplace components types you can use include: +The types of Marketplace components you can use include: * **[Plugin](/plugins/mia-platform-plugins.md)**: a ready-to-use Microservice. @@ -18,6 +18,14 @@ The Marketplace components types you can use include: * **[Application](/marketplace/applications/mia_applications.md)**: a bundle of resources including Plugins, Templates, and Examples, but also Endpoints, Collections, and Public Variables. +* **[Proxy](/development_suite/api-console/api-design/proxy.md)**: specific configurations used to invoke APIs that are external to the current project, but may be provided by an external service or another project. + +* **[Sidecars](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_sidecar.md)**: secondary utility containers running side by side with the main container in the same host. + +* **[Infrastructure Resources](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_infrastructure_resource.md)**: custom objects that are not part of the standard Console supported resources. + +* **[Extensions](/console/company-configuration/extensions.md)**: custom page that enhances Console capabilities by integrating it into the sidebar navigation. + :::info Mia-Platform supported Templates and Example source code is open source software, hosted on public Git repositories. @@ -44,7 +52,7 @@ The results of your search will always appear organized by Category. :::info -You can contribute to the Mia-Platform Marketplace by creating and sharing your own items. Find out more about how to [create your Company Marketplace](/marketplace/add_to_marketplace/create_your_company_marketplace.md). +You can contribute to the Mia-Platform Marketplace by creating and sharing your own items. Find out more about how to [create your Company Marketplace](/software-catalog/manage-items/overview.md). ::: @@ -82,3 +90,28 @@ The item will be marked as **Deprecated**. While you can still use it if necessa It's important to consider the alternatives to a deprecated item. Using updated and supported items ensures better performance, security, and compatibility. ::: + +### Set controlled versions for your Marketplace resources and make them available to users + +:::info +This feature is currently available for the [Plugin](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_plugin.md), [Infrastructure Resource](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_infrastructure_resource.md), [Templates and Examples](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_template_or_example.md) types. +::: + +Marketplace creators have now the possibility to manage some types of resources through a governance based on a versioning system. + +This means that, for these types of resources, it is possible to establish a more structured and transparent lifecycle management system, providing users access to all the versions of a resource and allowing them to see the release notes of each version and select and instantiate the version that best suits their configuration needs among the ones made available by the Marketplace creator. + +This versioning system also provides significant advantages in a feature-branch design workflow, effectively leveraging different versions of the same Marketplace item across various branches of a project. + +![CRUD-version](./img/item-version.png) + +For instance, we imagine to have a project with three different revisions: *dev*, *stage* and *main*, with the latter being the branch with the official configuration. Let's also imagine to have installed in all the three revisions the *CRUD Service* plugin, which includes different versions. + +In this scenario we can have: + +- the `main` branch with the `6.6.0` version, which is the supported version in our project +- we can use the the version `6.10.0` in the `stage` branch where the latest manual tests and verifications are performed before to be included in the `main` branch +- at the same time we can experiment and test features using the version `7.0.0` in your `dev` branch without affecting the other branches and the existing configurations + +This approach facilitates a smooth upgrade process, enables thorough testing of new features, and ensures compatibility across different stages of your project lifecycle. This flexibility allows for testing new versions in development environments while maintaining stable versions in production. +Such a structured approach will streamline resource management and ensure compatibility and stability across different use cases. diff --git a/docs/marketplace/templates/mia_templates.md b/docs/marketplace/templates/mia_templates.md index 3996a0146a..577ae7ea51 100644 --- a/docs/marketplace/templates/mia_templates.md +++ b/docs/marketplace/templates/mia_templates.md @@ -21,6 +21,6 @@ Mia-Platforms currently supports the following examples: | [Ktor template](https://github.com/mia-platform-marketplace/Ktor-Template) | Ktor, Kotlin | | [Ktor multi module template](https://github.com/mia-platform-marketplace/Ktor-Multi-Module-Template) | Ktor, Kotlin | . | -You can also [build a template](/marketplace/add_to_marketplace/add_item_by_type/add_template_or_example.md) by yourself. +You can also [build a template](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_template_or_example.md) by yourself. -Head to the [Create your Company Marketplace](/marketplace/add_to_marketplace/create_your_company_marketplace.md) page for further information on how to create and upload it to the Marketplace. +Head to the [Create your Company Marketplace](/software-catalog/manage-items/overview.md) page for further information on how to create and upload it to the Marketplace. diff --git a/docs/release-notes/img/software-catalog-add-item.png b/docs/release-notes/img/software-catalog-add-item.png new file mode 100644 index 0000000000..3105817823 Binary files /dev/null and b/docs/release-notes/img/software-catalog-add-item.png differ diff --git a/docs/release-notes/mia-platform-v13.mdx b/docs/release-notes/mia-platform-v13.mdx index 9153ebc854..beeeeda7d7 100644 --- a/docs/release-notes/mia-platform-v13.mdx +++ b/docs/release-notes/mia-platform-v13.mdx @@ -137,7 +137,7 @@ With Mia-Platform Software Catalog, you can: ### Versioning management of Marketplace resources | v13 - Fall Release Version control for your Marketplace resources is now available in Mia-Platform Console. Users can manage and access different versions of Plugins and infrastructure Resources, selecting the one that best suits their needs and easily switching between versions. -If you want to discover more, head to the [dedicated section](/marketplace/add_to_marketplace/create_your_company_marketplace.md#set-controlled-versions-for-your-marketplace-resources-and-make-them-available-to-users) inside the [Company Marketplace](/marketplace/add_to_marketplace/create_your_company_marketplace.md) documentation page. +If you want to discover more, head to the [dedicated section](/software-catalog/manage-items/overview.md#set-controlled-versions-for-your-marketplace-resources-and-make-them-available-to-users) inside the [Company Marketplace](/software-catalog/manage-items/overview.md) documentation page. ![Versioning Management](img/versioning-management.png) diff --git a/docs/release-notes/v13.1.2.md b/docs/release-notes/v13.1.2.md new file mode 100644 index 0000000000..bd8063fc6c --- /dev/null +++ b/docs/release-notes/v13.1.2.md @@ -0,0 +1,30 @@ +--- +id: v13.1.2 +title: Version 13.1.2 +sidebar_label: v13.1.2 +image: "img/release-note-link-preview.png" +--- + +_November 21th, 2024_ + +## Console + +### Bug Fix + +This version addressed the following bugs: + +* tenant selection during project creation and default provider management for companies with manually-managed tenant identifier; +* fixed a bug that prevented to use the '%' character in a template of the Infrastructure Resources generator. + +## Fast Data + +### Bug Fix + +This version addressed the following bugs: + +* It has been fixed an issue that prevented the feedback on the reducing step of Fast Data Control Plane frontend from being displayed correctly if a projection belongs to more than one single view pipelines. + +## How to update your Console + +For self-hosted installations, please head to the [self hosted upgrade guide](/infrastructure/self-hosted/installation-chart/100_how-to-upgrade.md) or contact your Mia-Platform referent and upgrade to _Console Helm Chart_ `v13.7.2-hotfix.0`. + diff --git a/docs/release-notes/v13.2.0.md b/docs/release-notes/v13.2.0.md index 3013322a22..8cccd5cb45 100644 --- a/docs/release-notes/v13.2.0.md +++ b/docs/release-notes/v13.2.0.md @@ -32,9 +32,9 @@ This means that when selecting a versioned resource from the Marketplace, users ![Versioned Service](img/versioned-service.png) We believe that this new approach to managing Marketplace resources will bring significant benefits, especially when using a feature-branch design workflow. -If you want to discover more about the potentiality of Marketplace resource versioning and how it works, head to the [dedicated section](/marketplace/add_to_marketplace/create_your_company_marketplace.md#set-controlled-versions-for-your-marketplace-resources-and-make-them-available-to-users) inside the [Company Marketplace](/marketplace/add_to_marketplace/create_your_company_marketplace.md) documentation page. +If you want to discover more about the potentiality of Marketplace resource versioning and how it works, head to the [dedicated section](/software-catalog/manage-items/overview.md#set-controlled-versions-for-your-marketplace-resources-and-make-them-available-to-users) inside the [Company Marketplace](/software-catalog/manage-items/overview.md) documentation page. -Visit also the [Plugins](/marketplace/add_to_marketplace/add_item_by_type/add_plugin.md) and [Custom Resources](/marketplace/add_to_marketplace/add_item_by_type/add_custom_resource.md) documentations for more information about how to correctly create and manage them. +Visit also the [Plugins](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_plugin.md) and [Custom Resources](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_infrastructure_resource.md) documentations for more information about how to correctly create and manage them. ### See the original Marketplace item in your instantiated resource and the option to Detach it diff --git a/docs/release-notes/v13.4.0.md b/docs/release-notes/v13.4.0.md new file mode 100644 index 0000000000..8a67636d27 --- /dev/null +++ b/docs/release-notes/v13.4.0.md @@ -0,0 +1,196 @@ +--- +id: v13.4.0 +title: Version 13.4.0 Release Notes +sidebar_label: v13.4.0 +image: "img/release-note-link-preview.png" +--- + +_November 21th, 2024_ + +:::info +Mia-Platform Console v13.4.0 is **now in Preview** and will be generally available on December 5th. + +Console SaaS users can try out v13.4.0 latest improvements in Preview! Open a Service Request to ask for the creation of a sandbox Company in case you do not have access to any Company. + +For self-hosted installations, please read the [following guidelines](#how-to-update-your-console). +::: + +## Manage your resources from Mia-Platform Software Catalog + + +In this release, we’ve enhanced the Software Catalog section with new features to improve resource management. Users can now create new items, as well as create new versions for items that support versioning, directly from the Console UI. Additionally, we’ve introduced the possibility to delete both individual items and their versions, offering more flexibility in managing resources within the Catalog. + + +For more details, please refer to [the documentation](/software-catalog/manage-items/software-catalog-ui/overview.md). + +![software catalog add item](img/software-catalog-add-item.png) + +## Create versions for your Microservice Templates & Examples + +You can now create and manage versions for Microservice Templates and Examples, enabling structured lifecycle management for these resource types as well. +Users can easily view and instantiate Templates and Examples at a specific version within their configuration. + +## Configuration Saved webhook + +We have introduced the **Configuration Saved** webhook, which is triggered whenever the configuration for a Project is saved. +You can easily enable it from the dedicated Webhook section in Console. + +## Specificy the Rate limit for Endpoints' subroutes + +For configurations using [Envoy API Gateway](/runtime_suite/envoy-api-gateway/overview.md), you can now specify the rate limits for the subroutes of your Endpoints. +This will allow for more granular control over rate limiting at the subroute level. + +## Fine-Grained Access Control in Design section + +:::info +This feature is currently available as a **Closed Preview**. +For more information, head to the related [documentation page](/development_suite/api-console/api-design/fine-grained-access-control.md) and contact your Mia-Platform referent to learn how to enable it. +::: + +We have introduced a mechanism to restrict user actions in the Design section based on roles and predefined rules. +Users with sufficient permissions can define granular rules to control access to specific actions, enhancing governance and security across Projects. +In this way, if a user attempts to perform a restricted action and save a configuration that violates such rules, the system will block the action and return an error message. + +## Console + +### Improvements + +#### Monitoring of the Infrastructure Resources created from scratch + +It is now possible, using the dedicated interface in the Design area, to define the parameters required to monitor an infrastructure resource created from scratch from the runtime area. + +#### Changes to Extensions are shown immediately in the Console sidebar + +We have improved the experience on managing the Extensions, making any changes made by the user immediately visible in the sidebar, with no need to manually refresh the page anymore. + +#### Identities search case insensitive + +We have enhanced the experience when searching for specific identities (Users, Service Accounts, Groups) within the Access Management section, making the search case insensitive. + +### Bug Fix + +This version addressed the following bugs: + +* fixed a bug that made it impossible to change the type of a microservice environment variable from ‘Downward API’ to ‘Plain’; +* fixed a bug that made impossible to create a template without Kustomize +* fixed a bug that caused a wrong display of a company's cluster list has been corrected; +* fixed an issue that caused infinite loading on refresh of the History section in the Deploy area. + +## Fast Data + +### Fast Data Services + +#### Projection Storer + +The new version `v1.3.4` of the _Projection Storer_ is available! + +#### Bug Fix + +This version addressed a few bugs, here is a comprehensive list: + +* following the upgrade of GraalJS version, insufficient permissions on the service image prevented the initialization of GraalVM cache and therefore the execution of any custom cast function. Now they can be properly executed again. +* the logic of provided cast function `castToDate` has been overhauled, so that dates represented as Unix timestamp in millisecond that ranges between `-2147483648` (`1969-12-07T03:28:36.352Z`) and `2147483647` (`1970-01-25T20:31:23.647Z`) are now properly converted into their expected date. + +For more information check out the service [changelog](/runtime_suite/projection-storer/changelog.md). + +## Microfrontend Composer + +### Configurator + +#### Improvements + +##### Support for compose page options configuration + +From the applications modal it is now possible to configure the [`fetchConfigOnMount option`](https://micro-lc.io/docs/guides/applications/compose#fetchconfigonmount) to instruct micro-lc to retrieve the application configuration at each mount. + +### Back-Kit Library + +The new version `v1.5.10` of the back-kit library is available! + +Refer to back-kit [changelog](/microfrontend-composer/back-kit/changelog.md) for finer-grained details of new versions. + +#### Improvements + +##### New format for dates + +By specifying `format: date` or `format: time` and adding the flag `isPartialFormat` to true in `formOptions` it is now possible to use dates and time as simple strings and not ISO format. + +#### Bug Fix + +- Fixed query for writable views' lookup +- fixed typo in italian label on export/import delimiter option + +## Marketplace + +### Marketplace Updates + +#### Audit Trail + +The first version of the Audit Trail sidecar is available now! + +This sidecar allows you to collect audit logs from your microservice through a shared log file and sends them to Kafka after being processed and enriched with metadata. + +Check the sidecar documentation for additional information about architecture, configuration and usage. + +#### Care Kit + +A new version `2.9.1` of Care Kit is out! + +The new version includes upgrade to Node.js (now using v20) and several dependencies, plus some fixes to the existing components `ck-threshold-modal` and `add-plan-modal`. The first version of a new component `roles-and-permissions-modal` to manage roles and permissions is also introduced. + +#### FHIR Adapter + +A new patch version `1.0.4` of the FHIR Adapter is out! + +This version includes important updates to Node.js (now using v20) and its dependencies. + +#### Form Service + +A new minor version `2.1.0` of the Form Service Frontend is out! + +This version introduces the ability to customize the title of the expired modal, plus brings important upgrades to its dependencies. + +#### Messaging Service + +The new version `1.7.1` of the Messaging Service is out! + +In this release we replace automatically newline escape sequences (`\n`, `\n\r`, `\r` and `\r\n`) with the `
` tag in HTML email messages. + +#### Notification Manager + +The new version `2.4.1` of the Notification Manager is out! + +This version introduces a streamlined way to display all the notification messages sent on a Backoffice page. By leveraging a MongoDB view, all the most common Backoffice features and components (table, filters and pagination) are supported out of the box. + +Also, a bug has been fixed that caused notification settings to be not merged correctly when the `rule` field was not set. + +#### Teleconsultation Service + +The new version `2.0.1` of the Teleconsultation Service - both Backend and Frontend - is out! + +This patch version includes improvements and fixes to the documentation, default security policies and UI copies. + +#### Therapy and Monitoring Manager + +The new version `0.5.1` of the Therapy and Monitoring Manager is out! + +This minor version brings some dependency updates, plus some fixes and improvements in the integrated threshold validation, in particular now the validation results are stored alongside the detection. +Also, a new `values` field is available in the prototypes to map a human-readable name of a detection property to the object path where the corresponding value is stored, such allowing to have nested or array fields in the detection schema while keeping a more human-friendly property name to display to the user. + +#### Auth0 Client - 3.7.1 + +This patch includes a fix to logout redirect when query parameters are set in the redirect path. + +#### Auth0 Client - 3.7.0 + +The version `3.7.0` of the Auth0 Client is now available, adding the support for TLS connections with Redis. + +#### HTTP proxy manager + +The new version `3.1.0` comes with a security fix which redacts sensitive headers in logs and with the new environment variable `ADDITIONAL_HEADERS_TO_REDACT` to specify additional sensitive headers to be redacted. + +## How to update your Console + +For self-hosted installations, please head to the [self hosted upgrade guide](/infrastructure/self-hosted/installation-chart/100_how-to-upgrade.md) or contact your Mia-Platform referent and upgrade to _Console Helm Chart_ `v13.8.0-beta.0`. + + diff --git a/docs/release-notes/versions.md b/docs/release-notes/versions.md index 5de39c988d..86ae370037 100644 --- a/docs/release-notes/versions.md +++ b/docs/release-notes/versions.md @@ -7,9 +7,11 @@ slug: "/release-notes/versions" --- | Release | Release notes | |---------|--------------------------------------------| +| v13.4.0 | [Read the release notes](/release-notes/v13.4.0.md) | | v13.3.0 | [Read the release notes](/release-notes/v13.3.0.md) | | v13.2.1 | [Read the release notes](/release-notes/v13.2.1.md) | | v13.2.0 | [Read the release notes](/release-notes/v13.2.0.md) | +| v13.1.2 | [Read the release notes](/release-notes/v13.1.2.md) | | v13.1.1 | [Read the release notes](/release-notes/v13.1.1.md) | | v13.1.0 | [Read the release notes](/release-notes/v13.1.0.md) | | v13.0.8 | [Read the release notes](/release-notes/v13.0.8.md) | diff --git a/docs/runtime_suite/audit-trail/_category_.json b/docs/runtime_suite/audit-trail/_category_.json new file mode 100644 index 0000000000..cba47ae4b7 --- /dev/null +++ b/docs/runtime_suite/audit-trail/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Audit Trail", + "position": 10 +} \ No newline at end of file diff --git a/docs/runtime_suite/email-builder/10_overview_and_usage.md b/docs/runtime_suite/email-builder/10_overview_and_usage.md new file mode 100644 index 0000000000..8e9f7a1104 --- /dev/null +++ b/docs/runtime_suite/email-builder/10_overview_and_usage.md @@ -0,0 +1,45 @@ +--- +id: overview_and_usage +title: Email Builder +sidebar_label: Email Builder +--- + + + +## Overview + +The Email builder is a Mia-Care plugin that allows the user to create html email templates using the no code tool provided by [Waypoint](https://www.usewaypoint.com/). + +## Usage + +The email builder plugin exposes a React-based front-end at the `/email-builder` path. For the plugin to work correctly 4 query parameters need to present in the URL + +- `id`: It must contain the id that identifies the current template that is being edited +- `endpoint`: it must contain the path from which the template needs to loaded. It is also the endpoint used to save the new HTML template +- `jsonField`: it must contain the name of the property used to save the template in JSON format +- `htmlField`: it must contain the name of the property used to save the template in HTML format + +## How it works + +The email builder provides a user interface for creating email templates. This tool converts the graphical elements of the template into both a JSON object and an HTML file. + +The email builder enables users to save the HTML and JSON versions of the current template in a CRUD. Users can also download the template as a JSON file. Additionally, it supports importing a JSON template for modifying existing templates. Integrated in the plugin are already present some templates to start with. + +For the front-end to load correctly, the `id`, `endpoint` and `jsonField` query parameters are required. On opening the request `GET endpoint/id`, where `endpoint` and `id` are the value of the relative query parameters, is done to fetch the template. From the fetched template, the `jsonField` property is used to access the current JSON version of the template and load it. If the `jsonField` property of the fetched template is undefined an empty template is loaded instead. + +By clicking the Save button in the top right is it possible to save the current template remotely. To save the template, the email builder performs a PATCH rest call to the path `endpoint/id` with the following body: + +``` +{ + $set: { + jsonField: 'JSON template', + htmlField: 'HTML template' + } +} +``` + +If the query parameter `htmlField` is not passed in the URL the PATCH will fail automatically. diff --git a/docs/runtime_suite/email-builder/_category_.json b/docs/runtime_suite/email-builder/_category_.json new file mode 100644 index 0000000000..ce26ca3e4b --- /dev/null +++ b/docs/runtime_suite/email-builder/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Email Builder", + "position": 10 +} \ No newline at end of file diff --git a/docs/runtime_suite/http-proxy-manager/30_configuration.md b/docs/runtime_suite/http-proxy-manager/30_configuration.md index 25a61ddc50..f8df6a701a 100644 --- a/docs/runtime_suite/http-proxy-manager/30_configuration.md +++ b/docs/runtime_suite/http-proxy-manager/30_configuration.md @@ -26,6 +26,8 @@ The service use the following environment variables: - **EXPOSE_MANAGEMENT_APIS** (optional, default `false`): allows to control whether or not [management APIs](./20_how_to_use.md#management-api) are exposed by the service (please note that this flag can be used only when running in dynamic configuration mode); - **ALLOW_PROXY_OPTIMIZER** (optional, default to `true`): boolean that enables optimized proxy using reverse proxy and preventing saving body request in memory. Be careful, this optimization does not perform any retry, thus it is strongly suggested to configure the token validation endpoint in your proxy configuration; - **DELAY_SHUTDOWN_SECONDS** (optional, default to `10` seconds): seconds to wait before starting the graceful shutdown. This delay is required in k8s to await for the DNS rotation; +- **DISABLE_PROXY_CACHE** (optional, default `false`): allows to disable the in-memory proxy cache. Such cache is used to prevent excessive CRUD invocations (useful when you want to prevent any possible out-dated cache hit whenever the service is using Dynamic Configuration in the context of a scaled HA architecture) +- **BASE_PATH_MATCHERS** (optional): comma-separated list of paths that are used to let the service handle complex base paths when using dynamic proxy configuration (note: this function is not compatible with the non-optimized proxy configuration, make sure to set `ALLOW_PROXY_OPTIMIZER=true`). - **ADDITIONAL_HEADERS_TO_REDACT** (optional): comma separated values of additional headers to redact when logging. The following headers are always redacted: `Authorization`, `Cookie`, `Proxy-Authorization`, `Set-Cookie` and `Www-Authenticate`; :::caution @@ -167,10 +169,15 @@ Path parameters inside **targetBaseUrl** and **basePath** are only allowed for t The service requires a CRUD collection (named as you prefer) that provides all the different details regarding the external services to be proxied: each document **must** match the *proxy* schema specified in the [configuration schema](#configuration-schema). -:::caution -The *dynamic configuration* has the technical limitation of using just the first path component as **basePath**. This limitation comes from the inability to determine the CRUD's search query. Due to this limitation path parameters are not allowed inside **targetBaseUrl** and **basePath**. +:::tip +By default, when using the *dynamic configuration* only the first segment of the invoked path is used as base path to extract configurations from the database; in this scenario path parameters are not supported. + +**E.g.**: without `BASE_PATH_MATCHERS`, given a request with path `/one/two/three`, the **basePath** searched on CRUD is `/one`. + +Use the `BASE_PATH_MATCHERS` environment variable to provide one ore more base path matchers and let the service be able to extract more complex +base paths from the database. -**E.g.**: given a request with path `/one/two/three`, the **basePath** searched on CRUD is `/one`. +Assuming you set `BASE_PATH_MATCHERS=/my-path/:param,/another-path/test-api` and then invoke `/my-path/123/some-other-api`, the **basePath** searched on CRUD will be `/my-path/123`. ::: In order to configure correctly the CRUD collection, you can **import** the fields from this file. This file already enables the Client Side Field Level Encryption (CSFLE) for those fields with sensitive data. diff --git a/docs/runtime_suite/http-proxy-manager/changelog.md b/docs/runtime_suite/http-proxy-manager/changelog.md index 09a93d0f20..4fe7867d24 100644 --- a/docs/runtime_suite/http-proxy-manager/changelog.md +++ b/docs/runtime_suite/http-proxy-manager/changelog.md @@ -15,6 +15,13 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## 3.3.0 - 22-11-2024 + +### Added + +- `BASE_PATH_MATCHERS`: to make it possible to fetch complex base paths when using dynamic configuration rather than taking the first segment only. +- `DISABLE_PROXY_CACHE`: to make it possible to disable the in-memory proxy cache when using dynamic configuration. + ## 3.2.0 - 15-11-2024 ### Added diff --git a/docs/software-catalog/catalog-and-marketplace/overview.md b/docs/software-catalog/catalog-and-marketplace/overview.md new file mode 100644 index 0000000000..e9c011addc --- /dev/null +++ b/docs/software-catalog/catalog-and-marketplace/overview.md @@ -0,0 +1,108 @@ +--- +id: overview-catalog-and-marketplace +title: Catalog and Marketplace Items Visibility +sidebar_label: Catalog and Marketplace Items Visibility +--- + +## Software Catalog and Mia-Platform Marketplace Items visibility + +As a Console user, you can access both Mia-Platform public Marketplace and your Company Software Catalog. +While the Mia-Platform public Marketplace is composed by all the items publicly available in the Mia-platform catalog, the **Software Catalog** is a Company-specific private space where to create and manage the items which are available only for your Company. + +The **Mia-Platform public Marketplace** is a key resource within the development platform, providing a vast library of ready-to-use components designed to support the setup of a Company's project architecture. Since it is publicly accessible, all Companies can view and utilize the items it contains. + +However, while the **Software Catalog** is intended for Company-specific, private use, there may be scenarios where a Company wants to make an item available to all Companies or even publish it to the public **Mia-Platform Marketplace**. This allows for greater sharing and collaboration across Companies. Conversely, there might also be cases where an item initially available in the Mia-Platform Marketplace needs to be restricted to a single Company, making it private and exclusive to that Company’s catalog. + +This guide aims to assist the reader in managing the visibility of items across different visibility levels: from private to visible to all companies, from visible to all companies to public, or vice versa. + +:::caution + +The ability to modify the visibility of an item to other companies is restricted to users with the Company Owner or Project Administrator role. Additionally, users must have the `marketplace.manage.root` + permission to perform this action. + +::: + +:::info +To create an item, please follow [this](/software-catalog/manage-items/overview.md) dedicated guide. +::: + +## How to manage items visibility + +Managing the visibility of items can be done through three main methods: + +- PaaS Console installation: + - open an issue on Mia-Platform [Github community page](https://github.com/mia-platform/community) or contact your Mia-Platform referent. +- On-Premise Console installation: + - assign the [`marketplace.root.manage`](/development_suite/identity-and-access-management/console-levels-and-permission-management.md#console-root-level-permissions) permission + and use one of the following two methods: + - the metadata section of the item in the Software Catalog to adjust visibility settings. + - [`miactl apply`](/cli/miactl/30_commands.md#apply-1) to change the item visibility + - (_Deprecated_): use the [Console Backoffice](/microfrontend-composer/previous-tools/cms/guide_cms.md) to make your item accessible to other Companies. + + +## Public Visibility + +To make an item accessible to the public, i.e. any user that access the Console, even if not authenticated, you can set the `visibility.public` field to `true`. The default value is `false`, meaning that an item will not be exposed to the public. + +:::caution +By default, for retrocompatibility reasons, items without the `tenantId` are exposed to the public, regardless of the presence of the `visibility.public` field. + +Since v12.x.x, **the `tenantId` field is mandatory**; the upgrade script will take care of adding a default `tenantId` and `visibility.public: true` only to Mia-Platform supported Marketplace items. + +If you have any Marketplace item supported by you without a `tenantId`, **you have the responsibility to set a `tenantId`** to them. Failing to do so may result in errors in the next Console releases. Remember also to update their `visibility` according to your needs +::: + +### Porting a public Marketplace item to the Private Catalog + +In the event that you need to port an item originally available in the public Marketplace to the private Marketplace, the first step is to communicate this intention to Mia-Platform maintenance team through a [Service Request](https://makeitapp.atlassian.net/servicedesk/customer/portal/21) or via a [GitHub Discussion](https://github.com/mia-platform/community). + +Once the Mia-Platform team receives the request and assesses its feasibility, they will grant authorization to proceed with the porting and monitor migration activities. After obtaining the authorization to proceed with the porting, you will need to create a repository on your Git Provider and migrate the code of the item you want to transfer. During this phase, if necessary, you will also need to configure your CI/CD pipelines. + +Once the repository configuration is complete, the final operational step involves creating the Item Configuration following the [guide for creating items](/software-catalog/manage-items/overview.md). At this point, it's essential to notify the Mia-Platform maintenance team of the completion of the preceding steps, either through the previously opened service request or GitHub discussion. This will allow them to proceed with the removal of the old item and its related configurations (repositories, pipelines, etc.) from the publicly accessible Marketplace. + +### Porting an existing item to the Public Marketplace + +For porting an item from private to public, the procedure is very similar to the one previously discussed for porting an item from public to private. In this case, the first step is to create the new item in the public Marketplace, following the procedure to make your item available to other companies as well. + +Once this procedure is completed, and the item is effectively available on the public Marketplace, you can proceed with retiring the private item. This involves removing the Item Configuration and its related configurations such as repositories and pipelines. + +:::caution + +The repositories and pipelines should only be deleted if they have not been reused in defining the new item in the public Marketplace. + +::: + +## Enabling the visibility to all Companies + +To make an item from your Company accessible to other Companies, you need to modify its `visibility` property. Specifically, set the `allTenants` property within the `visibility` object to "true". + +After editing, the visibility property should look like this: + +```json +... +"visibility": { + "allTenants": true +} +... +``` + +Depending on whether the item is hosted on a public or private repository, you may have to perform additional actions, as described here below. + +### Open Source item + +If the repository where your item is located is public and freely accessible (open source), then you have completed the process, and your item can now be accessed and used by other Companies! + +### Item hosted on a private repository + +To allow the Console to access the private repository, you need to create a **Provider for Marketplace**, in which you will specify the credentials to access the Git Provider. Follow [these steps](/console/company-configuration/providers/configure-marketplace-provider.mdx) to learn how to create it. + +The Provider has to be created in the same Company where the item is created (defined in the property `companyId` of the item). + +:::info +Please note that, in order for your Software Catalog resources to be visible to other Companies, yor need to enable the *Allow access to all the Companies* switch, as explained [here](/console/company-configuration/providers/configure-marketplace-provider.mdx#step-2-provider-details). +This allows the Console to access Software Catalog items resources when they are created within a Project belonging to any Company. +::: + +After creating and connecting your Provider, locate it in the Providers section of the CMS and take note of the `providerId`; go back to the Software Catalog and edit the item that you want to publish, and set to it the property `providerId` with the value you copied from the provider. + +From this moment, your new item should be available to any Company! \ No newline at end of file diff --git a/docs/marketplace/add_to_marketplace/declarative_marketplace.md b/docs/software-catalog/manage-items/declarative-approach.md similarity index 97% rename from docs/marketplace/add_to_marketplace/declarative_marketplace.md rename to docs/software-catalog/manage-items/declarative-approach.md index f7a50e1c96..5d9f7d6602 100644 --- a/docs/marketplace/add_to_marketplace/declarative_marketplace.md +++ b/docs/software-catalog/manage-items/declarative-approach.md @@ -1,7 +1,7 @@ --- -id: declarative_marketplace -title: Manage your Marketplace Items with a Declarative Approach -sidebar_label: Marketplace Declarative Approach +id: declarative-approach +title: Manage your Items with a Declarative Approach +sidebar_label: Declarative Approach --- In addition to the basic use of the tool through individual application commands, such as list, get, and resource deletion, a *declarative* approach is recommended. This approach is based on the use of [miactl](/cli/miactl/10_overview.md) in combination with a [Git Provider and a CI/CD system](/console/company-configuration/providers/overview.md). @@ -82,7 +82,7 @@ Root The item names are purely indicative, this example is only to explain a potential use-case. -The JSON and YAML files above follow the structure explained [in the related documentation](/marketplace/add_to_marketplace/manage_marketplace_items.md). +The JSON and YAML files above follow the structure explained [in the related documentation](/software-catalog/manage-items/overview.md). Here is an example of the Inventory System plugin config file: diff --git a/docs/marketplace/add_to_marketplace/img/declarative_delete_mr.png b/docs/software-catalog/manage-items/img/declarative_delete_mr.png similarity index 100% rename from docs/marketplace/add_to_marketplace/img/declarative_delete_mr.png rename to docs/software-catalog/manage-items/img/declarative_delete_mr.png diff --git a/docs/marketplace/add_to_marketplace/img/declarative_fix_mr.png b/docs/software-catalog/manage-items/img/declarative_fix_mr.png similarity index 100% rename from docs/marketplace/add_to_marketplace/img/declarative_fix_mr.png rename to docs/software-catalog/manage-items/img/declarative_fix_mr.png diff --git a/docs/marketplace/add_to_marketplace/img/declarative_fix_pipeline_log.png b/docs/software-catalog/manage-items/img/declarative_fix_pipeline_log.png similarity index 100% rename from docs/marketplace/add_to_marketplace/img/declarative_fix_pipeline_log.png rename to docs/software-catalog/manage-items/img/declarative_fix_pipeline_log.png diff --git a/docs/marketplace/add_to_marketplace/img/declarative_mr.png b/docs/software-catalog/manage-items/img/declarative_mr.png similarity index 100% rename from docs/marketplace/add_to_marketplace/img/declarative_mr.png rename to docs/software-catalog/manage-items/img/declarative_mr.png diff --git a/docs/marketplace/add_to_marketplace/img/declarative_pipeline_log.png b/docs/software-catalog/manage-items/img/declarative_pipeline_log.png similarity index 100% rename from docs/marketplace/add_to_marketplace/img/declarative_pipeline_log.png rename to docs/software-catalog/manage-items/img/declarative_pipeline_log.png diff --git a/docs/marketplace/add_to_marketplace/img/inventory_system.png b/docs/software-catalog/manage-items/img/inventory_system.png similarity index 100% rename from docs/marketplace/add_to_marketplace/img/inventory_system.png rename to docs/software-catalog/manage-items/img/inventory_system.png diff --git a/docs/marketplace/add_to_marketplace/img/version_list.png b/docs/software-catalog/manage-items/img/version_list.png similarity index 100% rename from docs/marketplace/add_to_marketplace/img/version_list.png rename to docs/software-catalog/manage-items/img/version_list.png diff --git a/docs/marketplace/add_to_marketplace/img/versions_notifications.png b/docs/software-catalog/manage-items/img/versions_notifications.png similarity index 100% rename from docs/marketplace/add_to_marketplace/img/versions_notifications.png rename to docs/software-catalog/manage-items/img/versions_notifications.png diff --git a/docs/marketplace/add_to_marketplace/add_item_by_type/add_application.md b/docs/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_application.md similarity index 99% rename from docs/marketplace/add_to_marketplace/add_item_by_type/add_application.md rename to docs/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_application.md index 76e8f86968..5cb0e964f6 100644 --- a/docs/marketplace/add_to_marketplace/add_item_by_type/add_application.md +++ b/docs/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_application.md @@ -1,5 +1,5 @@ --- -id: add_application +id: create_application title: Create an Application sidebar_label: Create an Application --- @@ -33,7 +33,7 @@ Only the `services` field must be configured for an application configuration to ### Configure Services -The `service` object has the same structure found in the Plugins, Templates and Examples, as explained in the [dedicated paragraph](/marketplace/add_to_marketplace/add_item_by_type/add_plugin.md#properties-of-plugin-resources). +The `service` object has the same structure found in the Plugins, Templates and Examples, as explained in the [dedicated paragraph](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_plugin.md#properties-of-plugin-resources). Thus, if you plan to add a plugin, a template, or an example to your application you can follow the same configuration. Remember to add general details to every microservice, such as name and description. diff --git a/docs/marketplace/add_to_marketplace/add_item_by_type/add_custom_resource.md b/docs/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_infrastructure_resource.md similarity index 97% rename from docs/marketplace/add_to_marketplace/add_item_by_type/add_custom_resource.md rename to docs/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_infrastructure_resource.md index ac7f06b888..09a50f68b4 100644 --- a/docs/marketplace/add_to_marketplace/add_item_by_type/add_custom_resource.md +++ b/docs/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_infrastructure_resource.md @@ -1,5 +1,5 @@ --- -id: add_custom_resource +id: create_infrastructure_resource title: Publish your Infrastructure Resources to the Marketplace sidebar_label: Create an Infrastructure Resource --- @@ -15,7 +15,7 @@ Infrastructure Resources are basically defined by two fields: - the `apiVersion` field, which should be set to `custom-generator.console.mia-platform.eu/v1` for generic template-based Infrastructure Resources, or to the version of the Kubernetes API used by the resource in case of Kubernetes-specific Custom Resources - the `kind` field, which is the specific resource type of the resource -An Infrastructure Resource can be created from scratch or from an existing Marketplace item and added to your Project. Infrastructure Resources on the Marketplace follow the base Marketplace item schema defined in the ["Create your Company Marketplace" page](/marketplace/add_to_marketplace/create_your_company_marketplace.md#how-to-configure-a-new-item), with the _type_ field set to `custom-resource`. +An Infrastructure Resource can be created from scratch or from an existing Marketplace item and added to your Project. Infrastructure Resources on the Marketplace follow the base Marketplace item schema defined in the ["Create your Company Marketplace" page](/software-catalog/manage-items/overview.md#how-to-configure-a-new-item), with the _type_ field set to `custom-resource`. Infrastructure resource items in the Marketplace also support _versioning_, allowing you to update a resource without overwriting its previous versions. @@ -211,7 +211,7 @@ runtime: ## Create a new Infrastructure Resource -::: info +:::info In the following paragraphs, we are going to use the `miactl` tool to create a new Infrastructure Resource. Make sure to [configure miactl](/cli/miactl/20_setup.md) before proceeding with the next steps. @@ -351,7 +351,7 @@ When updating a Infrastructure Resource, it is recommended to create a new versi The new version should contain the updated resource definition and a release note detailing the changes. In case you are trying to overwrite a versioned Marketplace Infrastructure Resource, remember that only few fields can be modified. -For more information, refer to the [dedicated section on the "Create your Company Marketplace" page](/marketplace/add_to_marketplace/create_your_company_marketplace.md#editing-a-versioned-resource). +For more information, refer to the [dedicated section on the "Create your Company Marketplace" page](/software-catalog/manage-items/overview.md#editing-a-versioned-resource). #### Update non-versioned Infrastructure Resources diff --git a/docs/marketplace/add_to_marketplace/add_item_by_type/add_plugin.md b/docs/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_plugin.md similarity index 97% rename from docs/marketplace/add_to_marketplace/add_item_by_type/add_plugin.md rename to docs/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_plugin.md index 520727977e..b26e7519ec 100644 --- a/docs/marketplace/add_to_marketplace/add_item_by_type/add_plugin.md +++ b/docs/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_plugin.md @@ -1,5 +1,5 @@ --- -id: add_plugin +id: create_plugin title: Create a Plugin sidebar_label: Create a Plugin --- @@ -22,7 +22,7 @@ This means that, in the *Design* section, the `dockerImage` field is *read-only* ## Definition of a Plugin resource -Plugins should follow the Marketplace item schema defined in the related section of the ["Create your Company Marketplace" page](/marketplace/add_to_marketplace/create_your_company_marketplace.md#how-to-configure-a-new-item). +Plugins should follow the Marketplace item schema defined in the related section of the ["Create your Company Marketplace" page](/software-catalog/manage-items/overview.md#how-to-configure-a-new-item). The *type* field must be equal to `plugin`, and the content of the field `resources` to include only a property called `services`. Inside the `services` object, you should specify *only one property*, which is the plugin name as the key and the plugin configuration as the value. @@ -47,7 +47,7 @@ Each property described in the following paragraphs regarding the microservices Instead of `<>`, you must include the identifier of your service, which **must** be in `kebab-case` format and should not exceed the length of 63 characters. :::info -The definition of services, and the following information related to the list of fields applies also to [Templates and Examples](/marketplace/add_to_marketplace/add_item_by_type/add_template_or_example.md), with the difference that the `services` object in Templates and Examples can include more than one key, which means more than one service. +The definition of services, and the following information related to the list of fields applies also to [Templates and Examples](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_template_or_example.md), with the difference that the `services` object in Templates and Examples can include more than one key, which means more than one service. ::: Here below are listed all the properties that you can provide for each microservice item: @@ -310,7 +310,7 @@ You can update a Custom Resource Marketplace item by using the same `miactl mark While non-versioned items can be modified in place without any limitation (except for `itemId` and `tenantId` that identifies the resource to update), versioned Marketplace Custom Resource have some fields that cannot be modified. -If you want to do so, you must create a new version of the resource: for more information, refer to the [dedicated section on the _Create your Company Marketplace_ page](/marketplace/add_to_marketplace/create_your_company_marketplace.md#how-to-create-a-new-version-of-your-resource). +If you want to do so, you must create a new version of the resource: for more information, refer to the [dedicated section on the _Create your Company Marketplace_ page](/software-catalog/manage-items/overview.md#how-to-create-a-new-version-of-your-resource). Also remember that versioned elements does not allow the update of the `dockerImage` field, since the value is automatically tied with the released version: if you need to change the Docker Image, you should create a new version of the resource. diff --git a/docs/marketplace/add_to_marketplace/add_item_by_type/add_sidecar.md b/docs/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_sidecar.md similarity index 99% rename from docs/marketplace/add_to_marketplace/add_item_by_type/add_sidecar.md rename to docs/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_sidecar.md index 0daa828965..a1e4b54246 100644 --- a/docs/marketplace/add_to_marketplace/add_item_by_type/add_sidecar.md +++ b/docs/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_sidecar.md @@ -1,5 +1,5 @@ --- -id: add_sidecar +id: create_sidecar title: Publish your Sidecar to the Marketplace sidebar_label: Create a Sidecar --- diff --git a/docs/marketplace/add_to_marketplace/add_item_by_type/add_template_or_example.md b/docs/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_template_or_example.md similarity index 93% rename from docs/marketplace/add_to_marketplace/add_item_by_type/add_template_or_example.md rename to docs/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_template_or_example.md index 1580fcd8ac..553054ba9d 100644 --- a/docs/marketplace/add_to_marketplace/add_item_by_type/add_template_or_example.md +++ b/docs/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_template_or_example.md @@ -1,5 +1,5 @@ --- -id: add_template_or_example +id: create_template_or_example title: Create a Template or Example sidebar_label: Create a Template or Example --- @@ -8,7 +8,7 @@ A **Template** is a base repository from which users can build a new Microservic **Examples** are similar to Templates, the only difference is they provide a basic implementation of the business logic for a specific use case, that users can use as a starting point for their custom implementation. -Templates and Examples are very similar to [Plugins](/marketplace/add_to_marketplace/add_item_by_type/add_plugin.md): make sure you follow the creation steps, then read the paragraphs below to learn how to finalize the configuration. +Templates and Examples are very similar to [Plugins](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_plugin.md): make sure you follow the creation steps, then read the paragraphs below to learn how to finalize the configuration. ## The target @@ -137,6 +137,13 @@ Here is some useful advice to strengthen your items: - **Where to host the zip with the code**: If you code your template on GitHub you can access the zip file using the URL `https://github.com/<username>/<project-name>/archive/<branch>.tar.gz` - **`.mia-template/` folder**: This folder is used to overwrite files in the main directory and won't be committed in the created repository; you can use it to provide a different README file to developers or to store the images and the marketplace item configuration +- versions can be used to track technological or relevant updates in the template (e.g. to denote a new language version or core library used) + +:::info +Versions are not mandatory but highly recommended to avoid overwriting existing resources. + +Please note that differently from other versioned items, template and examples do not support version updates and notifications. +:::
Example of a Start From Code Template diff --git a/docs/marketplace/add_to_marketplace/img/awesome_service.png b/docs/software-catalog/manage-items/mia-ctl/create/img/awesome_service.png similarity index 100% rename from docs/marketplace/add_to_marketplace/img/awesome_service.png rename to docs/software-catalog/manage-items/mia-ctl/create/img/awesome_service.png diff --git a/docs/marketplace/add_to_marketplace/manage_marketplace_items.md b/docs/software-catalog/manage-items/mia-ctl/create/overview.md similarity index 59% rename from docs/marketplace/add_to_marketplace/manage_marketplace_items.md rename to docs/software-catalog/manage-items/mia-ctl/create/overview.md index c84b889e7f..3181a440e5 100644 --- a/docs/marketplace/add_to_marketplace/manage_marketplace_items.md +++ b/docs/software-catalog/manage-items/mia-ctl/create/overview.md @@ -1,26 +1,9 @@ --- -id: manage_marketplace_items -title: Manage Marketplace Items -sidebar_label: Manage Marketplace Items +id: overview-mia-ctl-create +title: Create item +sidebar_label: Create item --- -There are three main methods to create, modify and delete Marketplace items: - -- (recommended) Use [`miactl`](/cli/miactl/10_overview.md), the Mia-Platform command line interface tool. -- Open an issue on Mia-Platform [Github community page](https://github.com/mia-platform/community). - -## How to use `miactl` to manage the Marketplace - -First of all, you need to setup `miactl`, as explained in the [dedicated doc](/cli/miactl/20_setup.md). - -With the `miactl marketplace` subcommands, you can perform several actions, described here below. - -:::tip -If you need to handle many Marketplace items, we suggest the adoption of a [Declarative Approach](/marketplace/add_to_marketplace/declarative_marketplace.md). -::: - -### Create an item - :::info You need to have *Company Owner* or *Project Administrator* role at Company level to perform this action @@ -33,7 +16,7 @@ You have developed a new service (for example a NodeJS service) called "My Awesome Service". The service is a plugin, i.e. users are only required to configure it and deploy it in their project. You now want it to be available in the Marketplace of your Company. -First of all, you need to create a JSON file as explained in [this guide](/marketplace/add_to_marketplace/create_your_company_marketplace.md#how-to-configure-a-new-item). +First of all, you need to create a JSON file as explained in [this guide](/software-catalog/manage-items/overview.md#how-to-configure-a-new-item). Save the file, for example as `myAwesomeService.json` file. The file contents will look like this: @@ -266,81 +249,3 @@ For example, here is "My Awesome Service"'s card: Further information about the `apply` command can be found in the [dedicated doc](/cli/miactl/30_commands.md#apply). ::: - -### Update an item - -:::info -You need to have *Company Owner* or *Project Administrator* role at Company level to perform this action -::: - -Imagine now that you noticed that the description of "My Awesome Service" is not correct and you want to change it. - -First of all, download and save the latest version of the item configuration: - -```sh -miactl marketplace get ITEM_ID > myAwesomeService.json -``` - -where `ITEM_ID` is an alphanumerical id of the Marketplace item. -If you don't know the item id, use the `miactl marketplace list` command to list all the Marketplace Items. You can easily locate the one of interest by looking for its name. - -:::tip - -It is suggested to always download the Marketplace item just before updating it to make sure it works on the latest version. - -::: - -Edit your file following the steps described in the [Modifying the Marketplace Item](#enabling-the-visibility-to-all-companies); -once you are happy with the changes, save the file and apply it to the Marketplace: - -```sh -miactl marketplace apply -f myAwesomeService.json -``` - -You will see the outcome of the operation in the command output: - -```sh -1 of 1 items have been successfully applied: - - ID ITEM ID NAME STATUS - - 65368hf0c91d871a87afbcbf my-awesome-service My Awesome Service Updated -``` - -The changes are now reflected to the Console. - -### Update of versioned items - -Marketplace items of type *Plugin* and *Custom Resources* require a *version* object to determine the differences of the plugin definition over time. -In case you need to update the definition, you can update a versioned item only if you need to change some base fields (more details on the [Create your Company Marketplace](/marketplace/add_to_marketplace/create_your_company_marketplace.md) page), otherwise you can do so by creating a new version. - -You can create a new version of the plugin via [miactl](/cli/miactl/10_overview.md) by simply executing the [`apply`](/cli/miactl/30_commands.md#apply) command, in the same way as explained above, ensuring that the `itemId` and `tenantId` are the same but with a new version, and of course the `resource` object updated. - -As explained in the [Create your Company Marketplace](/marketplace/add_to_marketplace/create_your_company_marketplace.md) page, we suggest to follow the [Semantic Versioning](https://semver.org/) convention when defining the version of your item. -This will help you to keep track of the changes you made to the item over time, and help you understand the best version to use when configuring your project. - -### Delete an item - -:::info -You need either the *Company Owner* or *Project Administrator* role at Company level to perform this action -::: - -Imagine you notice that the service "My Awesome Service" is no longer useful for your Company and so you want to delete it. - -You can delete an item from the Marketplace by means of the `delete` command: - -```sh -miactl marketplace delete --object-id= -``` - -> The `object-id` is the `ID` you get when you apply the template, it is not the `itemId` - -The item is then deleted from the Marketplace. - -The deletion is permanent, but the file on your machine will not be deleted. -If you want, you can recreate the item on the Marketplace again by applying the file. - -## Open an issue on Mia-Platform Github community page - -To contribute to the Mia-Platform Marketplace using this method, start by opening an issue [here](https://github.com/mia-platform/community/issues/new?assignees=%40mia-platform%2Fsig-marketplace&labels=marketplace&projects=&template=marketplace-contribution.yaml&title=%5BNew+marketplace+item%5D%3A+). This issue will outline the necessary information for your request. -Subsequently, a Mia-Platform representative will take over the issue and contact you to collaboratively plan the addition of the component to the Mia-Platform Marketplace, following the guidelines described on [this documentation page](/marketplace/add_to_marketplace/create_your_company_marketplace.md). diff --git a/docs/software-catalog/manage-items/mia-ctl/delete/overview.md b/docs/software-catalog/manage-items/mia-ctl/delete/overview.md new file mode 100644 index 0000000000..a8ee4b5539 --- /dev/null +++ b/docs/software-catalog/manage-items/mia-ctl/delete/overview.md @@ -0,0 +1,24 @@ +--- +id: overview-mia-ctl-delete +title: Delete item +sidebar_label: Delete item +--- + +:::info +You need either the *Company Owner* or *Project Administrator* role at Company level to perform this action +::: + +Imagine you notice that the service "My Awesome Service" is no longer useful for your Company and so you want to delete it. + +You can delete an item from the Marketplace by means of the `delete` command: + +```sh +miactl marketplace delete --object-id= +``` + +> The `object-id` is the `ID` you get when you apply the template, it is not the `itemId` + +The item is then deleted from the Marketplace. + +The deletion is permanent, but the file on your machine will not be deleted. +If you want, you can recreate the item on the Marketplace again by applying the file. diff --git a/docs/software-catalog/manage-items/mia-ctl/overview.md b/docs/software-catalog/manage-items/mia-ctl/overview.md new file mode 100644 index 0000000000..f3e56e8fc2 --- /dev/null +++ b/docs/software-catalog/manage-items/mia-ctl/overview.md @@ -0,0 +1,18 @@ +--- +id: overview-mia-ctl +title: Mia-ctl +sidebar_label: Mia-ctl +--- + +Creation of a item for your Company consists of two steps. The first is writing a Marketplace Item configuration file, then you have to upload it to the Console by using [`miactl`](/cli/miactl/10_overview.md), the official Mia-Platform CLI tool. + +## How to use `miactl` to manage the Marketplace + +First of all, you need to setup `miactl`, as explained in the [dedicated doc](/cli/miactl/20_setup.md). + +With the `miactl marketplace` subcommands, you can perform several actions, described here below. + +:::tip +If you need to handle many Marketplace items, we suggest the adoption of a [Declarative Approach](/software-catalog/manage-items/declarative-approach.md). +::: + diff --git a/docs/software-catalog/manage-items/mia-ctl/update/overview.md b/docs/software-catalog/manage-items/mia-ctl/update/overview.md new file mode 100644 index 0000000000..8256d51a6f --- /dev/null +++ b/docs/software-catalog/manage-items/mia-ctl/update/overview.md @@ -0,0 +1,55 @@ +--- +id: overview-mia-ctl-update +title: Update item +sidebar_label: Update item +--- + +:::info +You need to have *Company Owner* or *Project Administrator* role at Company level to perform this action +::: + +Imagine now that you noticed that the description of "My Awesome Service" is not correct and you want to change it. + +First of all, download and save the latest version of the item configuration: + +```sh +miactl marketplace get ITEM_ID > myAwesomeService.json +``` + +where `ITEM_ID` is an alphanumerical id of the Marketplace item. +If you don't know the item id, use the `miactl marketplace list` command to list all the Marketplace Items. You can easily locate the one of interest by looking for its name. + +:::tip + +It is suggested to always download the Marketplace item just before updating it to make sure it works on the latest version. + +::: + +Edit your file following the steps described in the [Modifying the Marketplace Item](#enabling-the-visibility-to-all-companies); +once you are happy with the changes, save the file and apply it to the Marketplace: + +```sh +miactl marketplace apply -f myAwesomeService.json +``` + +You will see the outcome of the operation in the command output: + +```sh +1 of 1 items have been successfully applied: + + ID ITEM ID NAME STATUS + + 65368hf0c91d871a87afbcbf my-awesome-service My Awesome Service Updated +``` + +The changes are now reflected to the Console. + +### Update of versioned items + +Marketplace items of type *Plugin* and *Custom Resources* require a *version* object to determine the differences of the plugin definition over time. +In case you need to update the definition, you can update a versioned item only if you need to change some base fields (more details on the [Create your Company Marketplace](/software-catalog/manage-items/overview.md) page), otherwise you can do so by creating a new version. + +You can create a new version of the plugin via [miactl](/cli/miactl/10_overview.md) by simply executing the [`apply`](/cli/miactl/30_commands.md#apply) command, in the same way as explained above, ensuring that the `itemId` and `tenantId` are the same but with a new version, and of course the `resource` object updated. + +As explained in the [Create your Company Marketplace](/software-catalog/manage-items/overview.md) page, you must follow the [Semantic Versioning](https://semver.org/) convention when defining the version of your item. +This will help you to keep track of the changes you made to the item over time, and help you understand the best version to use when configuring your project. diff --git a/docs/software-catalog/manage-items/overview.md b/docs/software-catalog/manage-items/overview.md new file mode 100644 index 0000000000..a140591b47 --- /dev/null +++ b/docs/software-catalog/manage-items/overview.md @@ -0,0 +1,182 @@ +--- +id: overview-manage-items +title: Manage Items +sidebar_label: Manage Items +--- + +There are three main methods to create, edit and delete items: + +- (recommended) Use Software Catalog UI +- Use [`miactl`](/cli/miactl/10_overview.md), the Mia-Platform command line interface tool. +- Open an issue on Mia-Platform [Github community page](https://github.com/mia-platform/community). + +## Software Catalog Items + +An **Item** (also referred to as a **Component**) is the basic unit of creating a resource within the catalog and represents a software resource that can be utilized in Mia-Platform Projects. + +Based on the visibility level of the item, it may be made available in the [Mia-Platform Marketplace](/marketplace/overview_marketplace.md), which hosts various types of items designed for different use cases. + +Directly from the Mia-Platform Marketplace, users can instantiate items into their Projects, integrating them to streamline development and configuration workflows. + +### Item Types + +The Software Catalog support the following item types. + +- **Plugins**: items for which users have no access to the actual code. Users will still be able to download their Docker image, in order to configure and use them within their Projects. +- **Templates** and **Examples**: archives for which a new repository is generated. The developer will have direct access to the new repository (created in their Project scope) and will be able to evolve its code at will. A template is a repository that, net of the development environment and framework setup, is empty; an example, instead, also implements some features tailored to help the user better familiarize with the development environment. +- **Applications**: bundles of resources that can be created and configured in the Mia-Platform Console within a few clicks. [Applications](/marketplace/applications/mia_applications.md) are composed of microservices (Plugins, Examples, and Templates), endpoints, CRUD collections, and public variables. Users can monitor if all the resources composing an application have been correctly set up inside the project, as well as access their corresponding repository or configuration. +- **Proxies**: specific configurations used to invoke APIs that are not part of the current project but may be exposed by an external provider or another project. You can find more information about proxies in [this section](/development_suite/api-console/api-design/proxy.md). +- **Sidecars**: secondary utility containers running side by side with the main container in the same host. Find more [here](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_sidecar.md) +- **Infrastructure Resources**: custom objects that are not part of the standard Console supported resources. For more information, go to [this section](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_infrastructure_resource.md) +- **Extensions**: custom page that enhances Console capabilities by integrating it into the sidebar navigation. + +:::note +Items can be assigned a **Category** (e.g., Data Stream, Data Visualization, Insurance, Healthcare, etc.) to help organize and identify them. +::: + +## How to configure a new item + +In the following section we'll explore the common fields shared by all item types. + +Refer to the [detailed explanation by type](#marketplace-items-example-and-explanation) for the type-specific fields and examples of working JSON items entities. + +Here below are listed all the properties that should be provided for each type of item: + +- **`name`** (required): the item name +- **`tenantId`** (required): the ID of the Company the item belongs to +- **`itemId`** (required): the unique ID of the item +- **`description`**: a brief description (10 to 20 words) regarding the service functionalities +- **`type`**: the type of your item (plugin, template, example, application, proxy, etc...) +- **`documentation`**: information about the documentation of your item. It is an object composed by: + - **`type`**: the type of documentation. It can be `externalLink` or `markdown` + - **`url`**: the URL of the documentation. It can be an external URL or an internal one +- **`comingSoon`** and **`releaseStage`**: properties to identify the maturity of the item (learn how to configure them in a [dedicated section](/software-catalog/manage-items/overview.md#the-release-stage-of-a-new-item) later on this page) +- **`categoryId`**: a label to help categorize items by their purpose or use case. As specified before, categories are only created internally at Mia-Platform. The `categoryId` of a item uniquely specifies both the specific category and sub-category (e.g. Start from Code (category) - Node.js (subcategory) will be identified by the `categoryId` "nodejs"). The [available category IDs](/software-catalog/manage-items/overview.md#category-list) are listed below. +- **`supportedBy`**: a label to identify the company that has produced the item (only used if `supportedByImage` is not provided) +- **`imageUrl`** and **`supportedByImageUrl`**: respectively the image that will be associated with the item and the image that will be associated with the company that has produced it. +- **`version`**: the version of the item. It is an object composed by the following properties: + - **`name`** (required): the actual version of the item. You must use the [Semantic Versioning](https://semver.org/) format. + - **`releaseNote`**: a release note that will be displayed to the user when selecting the item during creation or updates based on items in a Console project; includes information about the changes introduced by the new version. + - **`security`**: a boolean to indicate if the item is security-related + +Each item is identified by the values of the **`tenantId`**, the **`itemId`** and the **`version.name`** properties. So, when you need to create a new item, be sure to provide unique values for these properties. + +:::info +To upload the *image* and *supportedByImage*, you can also use the `miactl marketplace apply` command adding the respective `image` and `supportedByImage` keys to the object. + +Refer to the [related miactl documentation](/cli/miactl/30_commands.md#apply) to know the exact specifications of such object. +::: + +### Item visibility and the `tenantId` field + +When creating a new item, you always need to set the `tenantId` related to the Company you are creating the item in. + +You can also contribute to the **Mia-Platform Marketplace** by making your item accessible to other Companies: visit [this page](/software-catalog/catalog-and-marketplace/overview.md) for further information on this point. + +:::caution +Not setting the `tenantId` is no longer supported and deprecated. +Elements without `tenantId` will be public even if the `visibility.public` field is not set. + +This behavior might change in the next Console releases. + +If you have any item without the `tenantId` property set, we recommend to do the following: + +- set the `tenantId` to any of your companies; +- set the `visibility` field according to your needs. See the [related doc](/software-catalog/catalog-and-marketplace/overview.md) for more information on this point. + +::: + +:::info +If you want to make your item accessible to other Companies, you can visit [this page](/software-catalog/catalog-and-marketplace/overview.md#enabling-the-visibility-to-all-companies). + +Also, to learn how to migrate an item from the public to private internal catalog and vice versa, please refer to the [dedicated page](/software-catalog/catalog-and-marketplace/overview.md#public-visibility). +::: + +### How to create a new version for your resource + +To create a versioned resource, you need to set a specific value for the `name` property of the `version` object to the resource definition, as explained in the ["How to configure a new item" section](#how-to-configure-a-new-item). + +Also, to provide continuity to the definition of the other versions of the same resource, the `tenantId` and the `itemId` properties must be the same for all the versions of the same resource. + +You can create a new version of an item even if that resource already exists without a version. In that case the non-versioned item will still be available in the Console, where it will be shown with a *N/A* value for version. + +If there are multiple version of the same item, one of these versions will be used as *latest version*. +This is the version that will be used as a reference when you will create a new microservice or a new resource choosing the item from the Marketplace. + +The latest version is going to be the one with the highest version, according to the [Semantic Versioning rules](https://semver.org/). +We suggest to follow these guidelines when assigning a version to your item, in order to easily determine which one is the latest. + + ![List of marketplace versions](./img/version_list.png) + +:::info +Also you will be informed if one or more of your resources attached to an item have updates. + +You can find a list of all the updates at the bottom of the sidebar menu with the list of all your services, as well as inside the detail page of the service that can be updated. + + ![Design page with notifications of new Marketplace versions](./img/versions_notifications.png) +::: + +#### Editing a versioned resource + +Versioned resources are defined to be immutable, to avoid that updates might overwrite previous configurations. However, they can still be edited if there is a need to update their metadata (e.g. the release note or the description of the item due to typos or other reasons). + +Editing a versioned resource is possible via `miactl`, however the following fields cannot be edited: + +- `itemId` +- `tenantId` +- the `name` property inside `version` object +- the `resources` property, that includes the specific resource definition + +Since items are defined by the `itemId`, the `tenantId` and the `version` name, attempt to modifying one of these three properties will cause the creation of a new item, completely separated from the previous one. + +Attemping to modify the `resources` property will cause an error, and the item will not be updated. In that case, you need to create a new version of the item. + +Also, the following fields are editable only in case the permission `marketplace.root.manage` has been granted to the user: + +- `supportedBy` +- `supportedByImage` +- `publishOnMiaDocumentation` +- `visibility` + +More information about these permissions are available in the [permissions documentation](/development_suite/identity-and-access-management/console-levels-and-permission-management.md#console-root-level-permissions). + +#### Version dependent properties + +Versioning of resources means that resources under version control consist of certain *dependent fields* that contribute to defining the version. These fields cannot be modified directly by the user but can only be updated through the creation of a new version of the resource. + +For instance: + +- a version of a Microservice Plugin is defined by its `dockerImage`. By following the resource versioning management, a change in this field will require the creation of a new version for such Plugin +- for Infrastructure Resources of type K8s the governance is quite similar: since Infrastructure Resources of type K8s are defined by their `apiVersion` and `kind`, in this scenario, the only way to be able to change them will be through the creation of a new version. + +By defining these fields as *version dependent*, we ensure that they cannot be modified by the user when adding a marketplace item to their project. Whenever a new Microservice is created from a Marketplace plugin with a specific version, the `dockerImage` field will automatically be shown as read-only, and the user will only be able to modify it by actually checking for other versions of the plugin. + +### The Release Stage of an Item + +When creating or updating an item, the user can add information to help users identifying the maturity of the item. + +There are 2 fields that define the release stage of an item: + +- the `comingSoon` field is boolean, setting it to true will show the *Coming Soon* label and will prevent users to use the item +- the `releaseStage` field can have the following values: + - *preview* + - *beta* + - *stable* (default) + - *deprecated* + a label will shown on the item according to the value of the field, except for the *stable* stage + +:::info +Setting both the `releaseStage` and the `comingSoon` fields is not permitted and would lead to inconsistencies; please set either field or none according to the item lifecycle status. +::: + +Refer to the [Items Lifecycle](/marketplace/overview_marketplace.md#marketplace-item-lifecycle) section for details about each specific release stage. + +### Items example and explanation + +Refer to the detailed explanations and examples for each item type: + +- [Plugins](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_plugin.md) +- [Templates and Examples](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_template_or_example.md) +- [Applications](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_application.md) +- [Sidecars](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_sidecar.md) +- [Infrastructure Resources](/software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_infrastructure_resource.md) \ No newline at end of file diff --git a/docs/software-catalog/manage-items/software-catalog-ui/create/img/software-catalog-create-item.png b/docs/software-catalog/manage-items/software-catalog-ui/create/img/software-catalog-create-item.png new file mode 100644 index 0000000000..54b6dce37a Binary files /dev/null and b/docs/software-catalog/manage-items/software-catalog-ui/create/img/software-catalog-create-item.png differ diff --git a/docs/software-catalog/manage-items/software-catalog-ui/create/img/software-catalog-create-new-version.png b/docs/software-catalog/manage-items/software-catalog-ui/create/img/software-catalog-create-new-version.png new file mode 100644 index 0000000000..f165051bed Binary files /dev/null and b/docs/software-catalog/manage-items/software-catalog-ui/create/img/software-catalog-create-new-version.png differ diff --git a/docs/software-catalog/manage-items/software-catalog-ui/create/img/software-catalog-create-version-from-this.png b/docs/software-catalog/manage-items/software-catalog-ui/create/img/software-catalog-create-version-from-this.png new file mode 100644 index 0000000000..df361a769b Binary files /dev/null and b/docs/software-catalog/manage-items/software-catalog-ui/create/img/software-catalog-create-version-from-this.png differ diff --git a/docs/software-catalog/manage-items/software-catalog-ui/create/overview.md b/docs/software-catalog/manage-items/software-catalog-ui/create/overview.md new file mode 100644 index 0000000000..bc63f88412 --- /dev/null +++ b/docs/software-catalog/manage-items/software-catalog-ui/create/overview.md @@ -0,0 +1,34 @@ +--- +id: overview-software-catalog-create +title: Create item +sidebar_label: Create item +--- + +To create a new item in the catalog, click on the "Add Item" button. This will open a user interface (UI) that guides you through the item creation process. The process is divided into the following steps: + +1. **Select the Item Type** +Choose the type of item you want to create from the available options. This will determine the set of fields and attributes you need to provide during the creation process. + +2. **Enter Metadata** +Fill in the necessary metadata for the item. This typically includes basic information such as the name, description, category, and any other required attributes. + +3. **Enter Specifics** +After entering the metadata, you will need to specify additional details for the item. A default schema of resources will be provided to assist you in adding the relevant specifics. This schema serves as a template to help ensure all necessary information is included and formatted correctly. + +Follow the on-screen instructions to complete the item creation process. Once all steps are completed, you can save and submit the item to be added to the catalog. + +![create item](./img/software-catalog-create-item.png) + +## Create a New Version + +Create a new version is available only for items that support versioning. To create a new version of an item, follow these steps: + +#### From the Version Overview Page +On the item’s overview page, you can create a new version by selecting the "Create New Version" option. Here, you can choose whether to start from an existing version or create the new version from scratch. + +![create new version](./img/software-catalog-create-new-version.png) + +#### From the Version Detail Page +You can also create a new version directly from the version detail page. Click on the button with the three dots to open the option to create a new version based on the version you are currently viewing. + +![create new version](./img/software-catalog-create-version-from-this.png) \ No newline at end of file diff --git a/docs/software-catalog/manage-items/software-catalog-ui/delete/img/delete-version.png b/docs/software-catalog/manage-items/software-catalog-ui/delete/img/delete-version.png new file mode 100644 index 0000000000..35aadbd670 Binary files /dev/null and b/docs/software-catalog/manage-items/software-catalog-ui/delete/img/delete-version.png differ diff --git a/docs/software-catalog/manage-items/software-catalog-ui/delete/overview.md b/docs/software-catalog/manage-items/software-catalog-ui/delete/overview.md new file mode 100644 index 0000000000..b2d16fb3a9 --- /dev/null +++ b/docs/software-catalog/manage-items/software-catalog-ui/delete/overview.md @@ -0,0 +1,13 @@ +--- +id: overview-software-catalog-delete +title: Delete item or Version +sidebar_label: Delete item or Version +--- + +If an item is versionable, you can delete any specific version of the item by using the dedicated Delete button available for each version. This allows you to remove individual versions without affecting the entire item or other versions. + +![delete version](./img/delete-version.png) + +For items that are not versionable, you can delete the entire item by using the `Delete Item` button. This will permanently remove the item from the catalog. + +Both actions are irreversible, so be sure to confirm your decision before proceeding with deletion. \ No newline at end of file diff --git a/docs/software-catalog/img/item-versions.png b/docs/software-catalog/manage-items/software-catalog-ui/img/item-versions.png similarity index 100% rename from docs/software-catalog/img/item-versions.png rename to docs/software-catalog/manage-items/software-catalog-ui/img/item-versions.png diff --git a/docs/software-catalog/img/table-filters.png b/docs/software-catalog/manage-items/software-catalog-ui/img/table-filters.png similarity index 100% rename from docs/software-catalog/img/table-filters.png rename to docs/software-catalog/manage-items/software-catalog-ui/img/table-filters.png diff --git a/docs/software-catalog/img/versions-navigation.png b/docs/software-catalog/manage-items/software-catalog-ui/img/versions-navigation.png similarity index 100% rename from docs/software-catalog/img/versions-navigation.png rename to docs/software-catalog/manage-items/software-catalog-ui/img/versions-navigation.png diff --git a/docs/software-catalog/ui.md b/docs/software-catalog/manage-items/software-catalog-ui/overview.md similarity index 96% rename from docs/software-catalog/ui.md rename to docs/software-catalog/manage-items/software-catalog-ui/overview.md index 2bfa9fd237..0a12e654aa 100644 --- a/docs/software-catalog/ui.md +++ b/docs/software-catalog/manage-items/software-catalog-ui/overview.md @@ -30,7 +30,7 @@ At the top of the page, a breadcrumb navigation trail provides users with a stra ### Versions -If the item selected supports versioning, the first page will display a list of available versions. Each version includes key information such as the release date and, if available, a release note. For more details on versioning and how to manage it, please refer to [this documentation](/marketplace/add_to_marketplace/create_your_company_marketplace.md#item-types). +If the item selected supports versioning, the first page will display a list of available versions. Each version includes key information such as the release date and, if available, a release note. For more details on versioning and how to manage it, please refer to [this documentation](/software-catalog/manage-items/overview.md#item-types). By selecting a version, you are taken to the details specific to that version. From there, you can continue to navigate between versions or other related items using the breadcrumb navigation at the top of the page, ensuring a smooth transition between different resources. diff --git a/docs/software-catalog/overview.md b/docs/software-catalog/overview.md index 294f3b75eb..337ae1b81f 100644 --- a/docs/software-catalog/overview.md +++ b/docs/software-catalog/overview.md @@ -31,7 +31,7 @@ The catalog supports the following item types: - *proxy*: centralizes external API access and cross-namespace microservice communication, simplifying configuration; - *extension*: expands the Console with custom sections. -Please refer to [this documentation](/marketplace/add_to_marketplace/create_your_company_marketplace.md#item-types) for more details on item types. +Please refer to [this documentation](/software-catalog/manage-items/overview.md#item-types) for more details on item types. ### Items Versioning @@ -39,7 +39,7 @@ Please refer to [this documentation](/marketplace/add_to_marketplace/create_your This feature is currently available for the Plugin and Infrastructure Resource types. ::: -The versioning system in the Software Catalog provides detailed control over the different iterations of each item. For technical details on how versioning works, please refer to [this documentation](/marketplace/add_to_marketplace/create_your_company_marketplace.md#item-types). +The versioning system in the Software Catalog provides detailed control over the different iterations of each item. For technical details on how versioning works, please refer to [this documentation](/software-catalog/manage-items/overview.md#item-types). Each version includes key information, such as the release date and whether it is marked as the latest version. Additionally, if available, you can view the associated release notes to understand what changes or improvements were made in that particular version. @@ -55,6 +55,6 @@ Each item in the Software Catalog is associated with a lifecycle status that ref - stable - deprecated -For a more detailed explanation of each status, please refer to the [dedicated section](/marketplace/add_to_marketplace/create_your_company_marketplace.md#the-release-stage-of-a-marketplace-item) of the documentation. +For a more detailed explanation of each status, please refer to the [dedicated section](/software-catalog/manage-items/overview.md#the-release-stage-of-a-marketplace-item) of the documentation. A lifecycle status indicates where an item stands in its lifecycle, from its initial creation to its active use, and eventually to being deprecated when it's no longer maintained or supported. This helps users quickly understand the maturity and stability of an item. diff --git a/sidebars.json b/sidebars.json index 908cae4160..a393d4eb30 100644 --- a/sidebars.json +++ b/sidebars.json @@ -570,6 +570,10 @@ "id": "development_suite/api-console/api-design/security", "type": "doc" }, + { + "id": "development_suite/api-console/api-design/fine-grained-access-control", + "type": "doc" + }, { "collapsed": true, "items": [ @@ -1760,67 +1764,6 @@ } ] }, - { - "collapsed": true, - "label": "Marketplace Management", - "type": "category", - "items": [ - { - "label": "Create your Company Marketplace", - "type": "category", - "link": { - "id": "marketplace/add_to_marketplace/create_your_company_marketplace", - "type": "doc" - }, - "items": [ - { - "id": "marketplace/add_to_marketplace/add_item_by_type/add_plugin", - "label": "Create a Plugin Marketplace Item", - "type": "doc" - }, - { - "id": "marketplace/add_to_marketplace/add_item_by_type/add_template_or_example", - "label": "Create a Template or Example Marketplace Item", - "type": "doc" - }, - { - "id": "marketplace/add_to_marketplace/add_item_by_type/add_application", - "label": "Create an Application Marketplace Item", - "type": "doc" - }, - { - "id": "marketplace/add_to_marketplace/add_item_by_type/add_sidecar", - "label": "Create a Sidecar Marketplace Item", - "type": "doc" - }, - { - "id": "marketplace/add_to_marketplace/add_item_by_type/add_custom_resource", - "label": "Create a Custom Resource Marketplace Item", - "type": "doc" - } - ] - }, - { - "id": "marketplace/add_to_marketplace/manage_marketplace_items", - "type": "doc", - "label": "Manage Marketplace Items" - }, - { - "id": "marketplace/add_to_marketplace/marketplace_items_accessibility", - "type": "doc" - }, - { - "id": "marketplace/add_to_marketplace/change_marketplace_item_visibility", - "type": "doc", - "label": "Change Marketplace Items Visibility" - }, - { - "id": "marketplace/add_to_marketplace/declarative_marketplace", - "type": "doc", - "label": "Marketplace Declarative Approach" - } - ] - }, { "collapsed": true, "items": [ @@ -1915,6 +1858,10 @@ "id": "release-notes/versions" }, "items": [ + { + "id": "release-notes/v13.4.0", + "type": "doc" + }, { "id": "release-notes/v13.3.0", "type": "doc" @@ -1927,6 +1874,10 @@ "id": "release-notes/v13.2.0", "type": "doc" }, + { + "id": "release-notes/v13.1.2", + "type": "doc" + }, { "id": "release-notes/v13.1.1", "type": "doc" @@ -2000,7 +1951,91 @@ "type": "doc" }, { - "id": "software-catalog/ui", + "type": "category", + "collapsed": true, + "label": "Manage Items", + "link": { + "id": "software-catalog/manage-items/overview-manage-items", + "type": "doc" + }, + "items": [ + { + "type": "category", + "collapsed": true, + "label": "Software Catalog UI", + "link": { + "id": "software-catalog/manage-items/software-catalog-ui/ui", + "type": "doc" + }, + "items": [ + { + "id": "software-catalog/manage-items/software-catalog-ui/create/overview-software-catalog-create", + "type": "doc" + }, + { + "id": "software-catalog/manage-items/software-catalog-ui/delete/overview-software-catalog-delete", + "type": "doc" + } + ] + }, + { + "type": "category", + "collapsed": true, + "label": "Mia-ctl", + "link": { + "id": "software-catalog/manage-items/mia-ctl/overview-mia-ctl", + "type": "doc" + }, + "items": [ + { + "type": "category", + "collapsed": true, + "label": "Create Item", + "link": { + "id": "software-catalog/manage-items/mia-ctl/create/overview-mia-ctl-create", + "type": "doc" + }, + "items": [ + { + "id": "software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_plugin", + "type": "doc" + }, + { + "id": "software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_template_or_example", + "type": "doc" + }, + { + "id": "software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_application", + "type": "doc" + }, + { + "id": "software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_sidecar", + "type": "doc" + }, + { + "id": "software-catalog/manage-items/mia-ctl/create/create-item-by-type/create_infrastructure_resource", + "type": "doc" + } + ] + }, + { + "id": "software-catalog/manage-items/mia-ctl/update/overview-mia-ctl-update", + "type": "doc" + }, + { + "id": "software-catalog/manage-items/mia-ctl/delete/overview-mia-ctl-delete", + "type": "doc" + } + ] + }, + { + "id": "software-catalog/manage-items/declarative-approach", + "type": "doc" + } + ] + }, + { + "id": "software-catalog/catalog-and-marketplace/overview-catalog-and-marketplace", "type": "doc" } ]