Skip to main content
Version: 14.x (Next)

miactl

One of the possible ways to interact with the Catalog is through miactl, the Mia-Platform Command Line Interface.

tip

Before getting started, make sure you have completed the setup guide.

The commands related to the Catalog are described in the dedicated section

Declarative approach​

In addition to the basic use of the tool through individual application commands, miactl can be used in combination with a Git Provider and a CI/CD system to set a declarative management of the Catalog. This approach allows for a centralized management of the items, enabling supervised control of the state of resources, while extending the possibility of contribution to users without the necessary permissions (e.g., the use of Pull Requests/Merge Requests supervised by a maintainer).

The resources required to implement a declarative journey are:

tip

For a thorough explanation on supported Providers and how to configure them in the Console, consult this guide.

Creation of the repository​

The center of our journey is a Git repository that will store the [manifests][items-manifest] of the Catalog items, alongside any additional resource they might need (e.g., items logos).

The structure of the repository can vary, but a good setup may be something like the following one (actually taken from Mia-Platform Public Catalog repository).

Root
├── 📁 items
│   ├── 📁 <item-type>
│   │   ├── 📁 <item-id>
│   │   │   ├── 📁 assets
│   │   │   │   ├── 🖼️ logo.png
│   │   │   │   └── ...
│   │   │   └── 📁 versions
│   │   │       ├── 📄 <version-name>.json
│   │   │       ├── 📄 <version-name>.yaml
│   │   │       └── ...
│   │   └── ...
│   └── ...
└── ...

The folders hierarchical structure reflects that fact that each item has a type, at least one version, and, possibly, some assets. The JSON and YAML files inside the versions folders are the items [manifests][items-manifest].

Keeping in mind that the item names are purely indicative, this may be an example:

Root
├── 📁 items
│   ├── 📁 plugins
│   │   ├── 📁 inventory-system
│   │   │   ├── 📁 assets
│   │   │   │   ├── 🖼️ inventory_system_logo.png
│   │   │   └── 📁 versions
│   │   │       ├── 📄 1.0.0.json
│   │   │       ├── 📄 1.1.0.json
│   │   │       └── 
│   │   └── 
│   └──
└──

CI/CD Pipeline - An example with Gitlab​

The idea behind the automation of the managing process is to leverage a CI/CD tool to setup a pipeline that will apply all the manifests using miactl.

Any CI/CD tool will do the trick, but in this example we will focus on a Gitlab pipeline.

First of all, you need to create a service account on the Console, using, for example, the Client Secret Basic authentication.

With the account in place, create a CLIENT_ID and a CLIENT_SECRET Gitlab CI/CD Variable in your project and set the respective client-id and client-secret values you obtained during the setup of the service account.

tip

We suggest to mask the variable and to protect it, as suggested in Gitlab documentation.

Now write your pipeline in a .gitlab-ci.yml file with the following contents:

stages:
  - preparation
  - apply-catalog

variables:
  # make sure to use the latest miactl version available https://github.com/mia-platform/miactl/releases
  MIACTL_VERSION: "0.17.3"  

preparation:
  stage: preparation
  image: alpine:latest
  script:
    - apk add --no-cache git
    - git clone $CI_REPOSITORY_URL ./catalog-repo
    - cd ./catalog-repo

apply-catalog:
  stage: apply-catalog
  image: ghcr.io/mia-platform/miactl:$MIACTL_VERSION
  script:
    - 'echo "COMPANY_ID: $COMPANY_ID"'
    - 'echo "CONSOLE_ENDPOINT: $CONSOLE_ENDPOINT"'
    - miactl context auth new-auth --client-id $CLIENT_ID --client-secret $CLIENT_SECRET
    - miactl context set new-context --company-id $COMPANY_ID --endpoint $CONSOLE_ENDPOINT --auth-name new-auth
    - miactl context use new-context
    - miactl marketplace apply -f ./items

  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
caution

This pipeline is just an example. You may need to implement additional checks and use different images.

Here is an explanation of the environment variables needed in the pipeline:

  • MIACTL_VERSION: the version of miactl, make sure to always use the latest version in order to benefit the latest features and bug fixes.
  • CLIENT_ID: a secret env containing the service account client ID.
  • CLIENT_SECRET: a secret env containing the service account client secret.
  • CONSOLE_ENDPOINT: the base URL of your Console installation.
  • COMPANY_ID: the Company ID where you want the Catalog items to be created in.

Interaction with the repository​

One of the main benefits of following a declarative approach is that you can leverage the Git provider to setup a collaborative workflow, where developers can open Merge Requests to the Catalog repository, and Maintainers can approve and merge them.

In this way, even users without the permission to manage the Catalog directly can propose additions or changes, and curators can review and apply those changes.

Deleting an item​

When deleting an item or an item's version from the Catalog, keep in mind that you need to work both on the repository and on the Catalog itself, since a declarative approach usually works only in addition (i.e., deleting a manifest from the repository will not remove the item from the Catalog).

Therefore, remove the manifest from Git and use the miactl marketplace delete command to clean the Catalog.