Understanding the Deployment Manifest
Introduction
Deployment Manifest is the document which is used when deploying services using Mosaic Hosting Service to describe configuration related to the deployment and the service.
The full schema of the Deployment Manifest for V1 can be found at https://hosting.service.eu.axinom.net/.well-known/serviceDeploymentManifestSchema/1.0.
This document describes the structure of a deployment manifest document, and the elements which makes it.
For usage, please refer How to Deploy a Customized Service with Hosting Service.
Sample Deployment Manifest
version: '1.0'
serviceId: media-service
dnsMappedPorts:
- name: api
port: 10200
pilets:
- name: media_workflows
args:
MEDIA_SERVICE_BASE_URL: https://${__ax_hosted__.dns.self.api}
serviceAccounts:
- name: primary
permissionStructure:
- serviceId: ax-id-service
permissions:
- PERMISSIONS_SYNCHRONIZE
- ACCESS_TOKENS_GENERATE_LONG_LIVED_TOKEN
- serviceId: ax-image-service
permissions:
- IMAGE_TYPES_DECLARE
regularVariables:
POSTGRESQL_HOST: ${__ax_hosted__.pg.host}
POSTGRESQL_PORT: '${__ax_hosted__.pg.port}'
POSTGRESQL_USER_SUFFIX: '${__ax_hosted__.pg.user_suffix}'
PGSSLMODE: '${__ax_hosted__.pg.sslmode}'
DATABASE_NAME: '${__ax_hosted__.pg.database_name}'
RABBITMQ_PROTOCOL: '${__ax_hosted__.rmq.protocol}'
RABBITMQ_HOST: '${__ax_hosted__.rmq.host}'
RABBITMQ_PORT: '${__ax_hosted__.rmq.port}'
RABBITMQ_MGMT_PROTOCOL: '${__ax_hosted__.rmq.mgmt_protocol}'
RABBITMQ_MGMT_HOST: '${__ax_hosted__.rmq.mgmt_host}'
RABBITMQ_MGMT_PORT: '${__ax_hosted__.rmq.mgmt_port}'
RABBITMQ_VHOST: '${__ax_hosted__.rmq.vhost}'
NODE_ENV: production
SERVICE_ID: media-service
LOG_LEVEL: DEBUG
GRAPHQL_GUI_ENABLED: true
PORT: '${__ax_hosted__.port.api}'
TENANT_ID: '${__ax_hosted__.env.tenant_id}'
ENVIRONMENT_ID: '${__ax_hosted__.env.environment_id}'
IMAGE_SERVICE_BASE_URL: '${__ax_hosted__.svc.ax-image-service.management_base_url}'
CATALOG_SERVICE_BASE_URL: '${__ax_hosted__.dns.ax-catalog-service.api}'
ID_SERVICE_AUTH_BASE_URL: '${__ax_hosted__.svc.ax-id-service.auth_base_url}'
ENCODING_SERVICE_BASE_URL: '${__ax_hosted__.svc.ax-encoding-service.management_base_url}'
BILLING_SERVICE_END_USER_URL: '${__ax_hosted__.svc.ax-billing-service.end_user_base_url}'
secureVariables:
RABBITMQ_USER: '${__ax_hosted__.rmq.username}'
RABBITMQ_PASSWORD: '${__ax_hosted__.rmq.password}'
DATABASE_OWNER: '${__ax_hosted__.pg.db_owner_role}'
DATABASE_OWNER_PASSWORD: '${__ax_hosted__.pg.db_owner_password}'
DATABASE_LOGIN: '${__ax_hosted__.pg.db_login_role}'
DATABASE_LOGIN_PASSWORD: '${__ax_hosted__.pg.db_login_password}'
DATABASE_GQL_ROLE: '${__ax_hosted__.pg.db_gql_role}'
SERVICE_ACCOUNT_CLIENT_ID: '${__ax_hosted__.sa.client_id.primary}'
SERVICE_ACCOUNT_CLIENT_SECRET: '${__ax_hosted__.sa.client_secret.primary}'
Main Sections
The Deployment Manifest consists of the following sections. Each section describes configuration related to a specific domain of the service/deployment.
| Section Name | Description |
|---|---|
| version | Version of the Deployment Manifest Schema. At the moment the only supported value is "1.0". |
| serviceId | Service ID of the service which the Deployment Manifest belongs to. |
| dnsMappedPorts | Describes the ports, which the service exposes that will be mapped to DNS entries. When deploying, the DNS records will be created by looking at this section. |
| pilets | Describes deployment configuration for Pilets that will be deployed along with the service. It defines environment variables for each |
| serviceAccounts | Service Accounts required for the service are defined here, along with the permission sets that must be given to the accounts. When deploying, the Hosting Service will create these Service Accounts for the respective environment. |
| regularVariables | Regular Variables are environment variables that will be used by the deployed service. If concrete values are set, they will be stored as-received and will be used at deployment-time. If placeholders are used, they will be resolved into concrete values at deployment-time. |
| secureVariables | Secure environment variables to be used for the service deployment. If concrete values are set, they will be stored in a secure-storage automatically, and will be resolved to the concrete values at deployment-time. If placeholders are used, they will be resolved into concrete values at deployment-time. |
dnsMappedPorts
DNS Mapped Ports section describes the ports that the service exposes and how they
should be mapped DNS records that are created. Using a special placeholders,
the entries given in the dnsMappedPorts section can be referred and the value can be resolved
elsewhere in the Deployment Manifest, (i.e. in regularVariables section) as well.
A DNS Mapped Ports entry has the following properties.
| Property Name | Description |
|---|---|
| name | Identifier of the port. This name can be used elsewhere in the deployment manifest to refer to this port. |
| port | The port number which the service exposes that must be connected to the DNS entry that will be created. |
Placeholders for dnsMappedPorts
| Placeholder | Description |
|---|---|
${$$__ax_hosted__$$.dns.self.api} | This syntax can be used when referring to a port exposed in the same Deployment Manifest. |
${$$__ax_hosted__$$.dns.[service-name].api} | This syntax can be used to refer a port that is exposed through a different service, using the service ID. i.e. The following syntax refers to a port named api which is exposed by a service called ax-catalog-service. ${$$__ax_hosted__$$.dns.ax-catalog-service.api} |
pilets
The Pilets Section describes the configuration that must be used when publishing pilets in the deployment stage to the Mosaic Microfrontend Service.
| Property Name | Description |
|---|---|
| name | Name of the pilet. i.e. media-workflows |
| args | Environment variables that the pilet needs in the runtime. We can use placeholders here to refer to the port that was exposed through dnsMappedPorts. |
serviceAccounts
Service Accounts may be used when running the service to connect with other services
through GQL or RabbitMQ interfaces. This section describes how the service
accounts should be created, with what permissions. The service accounts defined
in this section can later be referred in the regularVariables or secureVariables sections
using placeholders.
|
Property Name |
Description |
Code |
|---|---|---|
|
name |
Identifier of the Service Account. This name can be used elsewhere in the deployment manifest to refer to this Service Account. | |
|
permissionStructure |
Permission structure for the Service Account. This is an array of entry, with each entry consisting
of a |
|
Placeholders for serviceAccounts
| Placeholder | Description |
|---|---|
${$$__$$ax_hosted$$__$$.sa.client_id.primary} | This syntax can be used when referring to the Client ID for a created Service Account. primary is the name of the Service Account. |
${$$__ax_hosted__$$.sa.client_secret.primary} | This syntax can be used when referring to the Client Secret for a created Service Account. primary is the name of the Service Account. |
regularVariables and secureVariables
Regular and Secure Variables sections define environment variables that must be present when running the
service. Any property defined in the regularVariables section will be stored as it is in the database.
If you have any variables that must be securely stored, such as API keys, it is recommended to use
secureVariables section to define those. Properties defined in secureVariables section
are stored in a secure vault and are only resolved at runtime, when they’re used.
Other Placeholders
These placeholders can be used anywhere in the Deployment Manifest document to resolve the respective value.
| Placeholder | Description |
|---|---|
${$$__$$ax_hosted$$__$$.env.tenant_id} | The Tenant ID for which the request is taking place (same as service-deployment record’s Tenant ID ) |
${$$__$$ax_hosted$$__$$.env.environment_id} | The Environment ID for which the request is taking place (same as service-deployment record’s Environment ID) |
${$$__$$ax_hosted$$__$$.pg.host} | The PostgresSQL DB Server hostname |
${$$__$$ax_hosted$$__$$.pg.port} | The PostgresSQL DB Server port |
${$$__$$ax_hosted$$__$$.pg.user_suffix} | The PostgresSQL DB Server user_suffix |
${$$__$$ax_hosted$$__$$.pg.sslmode} | The PostgresSQL DB Connection TLS mode |
${$$__$$ax_hosted$$__$$.pg.database_name} | Database name created via Hosting Service |
${$$__$$ax_hosted$$__$$.pg.db_owner_role} | DB Owner role name created via Hosting Service |
${$$__$$ax_hosted$$__$$.pg.db_owner_password} | DB Owner role password created via Hosting Service |
${$$__$$ax_hosted$$__$$.pg.db_login_role} | DB Login role name created via Hosting Service |
${$$__$$ax_hosted$$__$$.pg.db_login_password} | DB Login role password created via Hosting Service |
${$$__$$ax_hosted$$__$$.pg.db_gql_role} | DB GQL role name created via Hosting Service |
${$$__$$ax_hosted$$__$$.rmq.protocol} | The RMQ protocol |
${$$__$$ax_hosted$$__$$.rmq.host} | The RMQ Server hostname |
${$$__$$ax_hosted$$__$$.rmq.mgmt_protocol} | The RMQ Management protocol |
${$$__$$ax_hosted$$__$$.rmq.mgmt_host} | The RMQ Server management API hostname |
${$$__$$ax_hosted$$__$$.rmq.mgmt_port} | The RMQ Server management API port |
${$$__$$ax_hosted$$__$$.rmq.vhost} | RMQ VHOST created via Hosting Service |
${$$__$$ax_hosted$$__$$.rmq.username} | RMQ Username created via Hosting Service |
${$$__$$ax_hosted$$__$$.rmq.password} | RMQ Password created via Hosting Service |
${$$__$$ax_hosted$$__$$.svc.self.id} | Service ID of the service that is being deployed. |
${$$__$$ax_hosted$$__$$.svc.ax-id-service.auth_base_url} | Resolves to the Auth Base URL of ID Service. |
${$$__$$ax_hosted$$__$$.svc.ax-id-service.management_base_url} | Resolves to the ID Service Access Management Base URL. |
${$$__$$ax_hosted$$__$$.svc.ax-image-service.management_base_url} | Resolves to the Management Base URL of Image Service. |
${$$__$$ax_hosted$$__$$.svc.ax-encoding-service.management_base_url} | Resolves to the Management Base URL of Encoding Service. |
${$$__$$ax_hosted$$__$$.svc.ax-user-service.auth_base_url} | Resolves to the Auth Base URL of User Service. |
${$$__$$ax_hosted$$__$$.svc.ax-user-service.management_base_url} | Resolves to the Management Base URL of User Service. |
${$$__$$ax_hosted$$__$$.svc.ax-portal-service.management_base_url} | Resolves to the Management Base URL of Management System Service. |
${$$__$$ax_hosted$$__$$.svc.ax-micro-frontend-service.micro_frontend_base_url} | Resolves to the Base URL of Microfrontend Service. |
${$$__$$ax_hosted$$__$$.svc.ax-personalization-service.management_base_url} | Resolves to the Management Base URL of Personalization Service. |
${$$__$$ax_hosted$$__$$.svc.ax-monetization-grants-service.management_base_url} | Resolves to the Management Base URL of Monetization Grants Service. |
${$$__$$ax_hosted$$__$$.svc.ax-subscription-monetization-service.management_base_url} | Resolves to the Management Base URL of Subscription Monetization Service. |
${$$__$$ax_hosted$$__$$.svc.ax-billing-service.management_base_url} | Resolves to the Management Base URL of Billing Service. |
${$$__$$ax_hosted$$__$$.svc.x-billing-service.end_user_base_url} | Resolves to the End User Base URL of Billing Service. |