Skip to main content

Installation

OctoMesh uses Communication Operators to manage distributed computing resources using Kubernetes. The Communication Operators are responsible for managing the lifecycle of a Deployment Site's workloads (Adapters and Applications), including creating, updating, and deleting them.

Prerequisites​

  • An installed Communication Operator on a Kubernetes cluster. The operator is configured (via its OPERATOR__* environment variables / Helm values) with the Communication Controller URI and the message-broker connection it should use — these are properties of the operator instance, not of the individual Deployment Site.

Installation of a Deployment Site​

We want to install a Deployment Site named site-documentation for tenant meshtest in the namespace site-documentation.

Step 1: Create a Deployment Site runtime entity​

First, we need to create the Deployment Site as a runtime entity in the Asset Repository. The runtime entity is a System.Communication/DeploymentSite object. The following example shows the runtime entity for site-documentation:

$schema: https://schemas.meshmakers.cloud/runtime-model.schema.json
dependencies:
  - System.Communication
entities:
  - rtId: 65d5c447b420da3fb12381bb
    ckTypeId: System.Communication/DeploymentSite
    attributes:
      - id: System/Name
        value: site-documentation

This file can be imported in Refinery Studio under the Communication/Deployment Sites tab or using the octo-cli command line tool with command ImportRt.

CK type renamed in System.Communication 4.0.0

System.Communication/Pool became System.Communication/DeploymentSite, and the association role linking a workload to its site changed from Manages / ManagedBy to Hosts / HostedBy. Existing entities are converted by the 3.35.0 → 4.0.0 migration: rtId, well-known name and attribute values are preserved, only the CK type id changes. Runtime models written against the old type id need updating.

Step 2: Create a namespace and secret​

We need to create a secret for the connection to the message broker. The secret pattern is {TenantId}-{DeploymentSiteRtId}-octo-mesh-connection and is stored in the namespace site-documentation. The secret contains the username and password for the message broker. Using the runtime entity id 65d5c447b420da3fb12381bb from Step 1, the secret name is meshtest-65d5c447b420da3fb12381bb-octo-mesh-connection:

apiVersion: v1
kind: Secret
metadata:
  name: meshtest-65d5c447b420da3fb12381bb-octo-mesh-connection # {TenantId}-{DeploymentSiteRtId}-octo-mesh-connection
  namespace: site-documentation # Namespace of the Deployment Site, must match the DeploymentSite object's namespace
type: Opaque
data:
  brokerusername: ZGVtbw== # base64 encoded username for message broker
  brokerpassword: ZGVtbw== # base64 encoded password for message broker
note

Every Kubernetes name the operator derives for a Deployment Site — the secret name, labels, and (in central mode) the CR name — is built from the site's runtime entity id (DeploymentSiteRtId), because runtime entity ids are 24-character hex strings and therefore always valid Kubernetes names, whereas a human-readable site name may contain characters the API server rejects.

Step 3: Create a DeploymentSite custom resource​

Finally, we need to create a DeploymentSite object in the namespace site-documentation. The spec carries only the tenant identity and the site's runtime entity id (deploymentSiteRtId) — the canonical identity from Step 1. The Communication Controller URI and message-broker connection are read from the operator's own configuration, not from the CR:

apiVersion: octo-mesh.meshmakers.io/v1
kind: DeploymentSite
metadata:
  name: site-documentation  # Any valid Kubernetes name for the CR
  namespace: site-documentation # Namespace of the Deployment Site, must match the secret's namespace
spec:
  tenantId: "meshtest" # Tenant ID
  deploymentSiteRtId: "65d5c447b420da3fb12381bb" # rtId of the DeploymentSite runtime entity created in Step 1

After deployment of the DeploymentSite object, the Communication Operator will register the site with the Communication Controller. The Deployment Site is now ready to deploy workloads (Adapters and Applications).

Upgrading from a release before System.Communication 4.0.0

The custom resource was called CommunicationPool (communicationpools.octo-mesh.meshmakers.io, API version v1alpha1) and its spec field was poolRtId. There is no in-place conversion: the old CRD is removed and the new one installed, which deletes the existing custom resources with it. Recreate each Deployment Site afterwards — the Communication Controller holds every site as a runtime entity, so redeploying from Refinery Studio or octo-cli is enough.

The old CRD carries helm.sh/resource-policy: keep, so a Helm upgrade will not remove it. Delete it explicitly:

kubectl delete crd communicationpools.octo-mesh.meshmakers.io

The Helm values that configure the operator were renamed in the same release: operator.autoManagePools → operator.autoManageDeploymentSites, operator.poolNamespace → operator.deploymentSiteNamespace, operator.defaultPoolName → operator.defaultDeploymentSiteName.