Contributing to Connections

Connections are schema-driven. A Connection’s structure, identity, lifecycle, and the forms Meshery renders for it are declared in a connection definition that conforms to the Connection schema (connections.meshery.io/v1beta3) in meshery/schemas. Before contributing, familiarize yourself with that schema and read Contributing to Schemas for the development workflow.

This guide explains how to author a connection definition so that Meshery understands a new kind of Connection and offers it in the Connection Wizard. In most cases, authoring a JSON definition is all you need - no UI or server code.

For the configuration contract for AI inference services, see AI provider Connections.

What is a connection definition?

A connection definition is a first-class Registry entity, authored per Model - exactly like Components and Relationships. It declares everything Meshery needs to register, render, and manage a kind of Connection:

  • its identity (kind, type, subType),
  • its lifecycle (initial status and a transitionMap of allowed state transitions),
  • the forms the Connection Wizard renders (connectionSchema and credentialSchema), and
  • its visual identity (styles).

Anatomy of a connection definition

Below is a complete, minimal definition for a hypothetical telemetry backend. It uses the generic wizard flow, which is what most contributions should use.

	
		{
  "schemaVersion": "connections.meshery.io/v1beta3",
  "name": "Grafana",
  "description": "A Grafana instance that brings its dashboards and panels into Meshery.",
  "kind": "grafana",
  "type": "telemetry",
  "subType": "metrics",
  "status": "registered",
  "transitionMap": {
    "registered": [
      { "nextState": "connected", "description": "Connect to the Grafana instance." },
      { "nextState": "ignored", "description": "Keep the registration but do not connect." }
    ],
    "connected": [
      { "nextState": "disconnected", "description": "Disconnect the Grafana connection." },
      { "nextState": "deleted", "description": "Remove the Grafana connection completely." }
    ]
  },
  "connectionSchema": {
    "type": "object",
    "title": "Grafana Connection",
    "required": ["url"],
    "properties": {
      "url": {
        "type": "string", "format": "uri", "title": "Grafana Endpoint",
        "description": "Base URL of the Grafana instance (e.g. http://grafana.example:3000)."
      },
      "name": {
        "type": "string", "title": "Connection Name",
        "description": "Optional friendly name for this Grafana connection."
      }
    }
  },
  "credentialSchema": {
    "type": "object",
    "title": "Grafana Credential",
    "properties": {
      "secret": {
        "type": "string", "title": "API Key or Basic Auth",
        "description": "API key, or basic-auth credential formatted as username:password."
      }
    }
  },
  "styles": {
    "svgColor": "<svg ...>...</svg>",
    "svgWhite": "<svg ...>...</svg>"
  }
}
	

Identity: kind, type, subType

These three fields identify the Connection and determine how the wizard treats it:

  • kind - the genre of Connection (e.g. grafana, prometheus, kubernetes). The wizard groups credentials and renders icons by kind.
  • type - a broad classification: platform, telemetry, source, collaboration, and so on.
  • subType - a finer classification: orchestration, metrics, git, registry, chat, and so on.

Together they let the UI target a specific Connection with a custom wizard extension when the generic flow is not enough. For reference, the definitions Meshery ships with:

ConnectionkindtypesubTypeinitial status
Kuberneteskubernetesplatformorchestrationdiscovered
Grafanagrafanatelemetrymetricsregistered
Prometheusprometheustelemetrymetricsregistered
Artifact Hubartifacthubsourceregistryregistered
GitHubgithubsourcegitregistered

Lifecycle: status and transitionMap

status is the state a freshly created Connection starts in. Manually registered Connections typically start at registered; resources that Meshery discovers (like Kubernetes) start at discovered.

transitionMap declares the state machine for the Connection: for each state, the list of states it may move to, each with a human-readable description shown as a confirmation prompt in the UI. Use only the canonical states - discovered, registered, connected, disconnected, ignored, maintenance, deleted, and not found - and keep the transitions consistent with their documented meanings. See States and the Lifecycle of Connections for what each state means and which transitions make sense.

Forms: connectionSchema and credentialSchema

Both are JSON Schemas. The Connection Wizard renders them directly with react-jsonschema-form - the same library used for Component forms:

  • connectionSchema becomes the Configure Connection step. Mark the fields a Connection cannot exist without (such as url) as required. A name property, if present, is used as the Connection’s display name.
  • credentialSchema becomes the Associate Credential step. Omit it for a Connection that needs no secret - the wizard then skips the credential step entirely.

Because these schemas live on the definition, the wizard needs no per-kind UI code to render them. Adding a property to the schema adds a field to the form.

How a credential’s secret is persisted - and read

The canonical form, declared in meshery/schemas, is a top-level name plus a secret object holding the kind-specific fields. The persisted secret object is the payload.

Four shapes exist in stored data in total - the canonical one plus three others - and Meshery reads all of them. Two of the three non-canonical shapes are still written today: Meshery writes the Kubernetes shape when it imports a kubeconfig, and its credential form writes the double-nested wrapper.

ShapeStored secretWhere the payload is
Canonical{"grafanaURL": "...", "grafanaAPIKey": "..."}the object itself
Kubernetes{"auth": {...}, "cluster": {...}}the object itself
Legacy double-nested{"credentialName": "x", "secret": {...}}one level down
Legacy string{"secret": "<token>"}a bare string

Legacy rows are never rewritten - tolerance is what keeps them working. Two mirrored helpers own the whole decision, and every read site goes through them rather than reaching into the map:

  • Go - models.CredentialPayload (the object carrying the credential’s fields) and models.CredentialAuthSecret (the string auth material) in server/models/credential_secret.go.
  • TypeScript - resolveCredentialPayload and resolveCredentialAuthSecret in ui/utils/credentialSecret.ts.

Ambiguity resolves toward the canonical shape: an object is only unwrapped when it consists of nothing but the legacy wrapper keys (credentialName, name, secret), so a canonical payload that happens to carry its own secret field is left alone. The one shape this cannot distinguish is a payload whose only fields are name and secret - no canonical form has that shape, so keep a new credential kind’s payload away from it.

What must stay in step between the two files is the resolution rules, not the return types: the helpers deliberately differ on the legacy string shape, where the TypeScript resolveCredentialPayload returns the bare string and the Go CredentialPayload returns nil because it is typed to a map (Go callers use CredentialAuthSecret). The auth-key list is currently grafana only; a credential kind whose canonical form holds string auth material under a new property must be added to canonicalAuthSecretKeys and CANONICAL_AUTH_SECRET_KEYS.

The helpers resolve the wrapper, not the field names inside it. A Kubernetes credential created through the credential form describes its cluster with clusterName/clusterServerURL rather than the kubeconfig-style cluster block K8sContextFromConnection reads, so it yields an auth block but no cluster; which side moves is tracked in meshery/meshery#21336.

Visual identity: styles

styles carries inline SVG markup for the kind’s icon: svgColor (for light backgrounds), svgWhite (for dark backgrounds), and optionally svgComplete. Follow the same icon conventions as Components.

Optional metadata

Two optional metadata keys tune wizard behavior:

  • metadata.flow - force a wizard flow: generic (the default for every kind except Kubernetes) or kubernetes. You rarely need to set this.
  • metadata.docsURL - a documentation link surfaced for the kind in the wizard. Defaults to the Connections concept page.

Where the definition lives

Place the definition as a JSON file in a connections/ folder inside its Model, alongside that Model’s components/ and relationships/:

models/<model>/<version>/connections/<Name>Connection.json

For example, the shipped definitions live under models/meshery-core/.../connections/ as KubernetesConnection.json, GrafanaConnection.json, PrometheusConnection.json, ArtifactHubConnection.json, and GitHubConnection.json. A Model may include any number of connection definitions. Use these existing files as templates.

How the definition is registered and consumed

  1. Registration. On Model registration, Meshery registers the connection definition into the Registry under its Model and registrant - the same path as Components and Relationships. A Model (carrying a registrant) is required. Definitions can also be managed over the registry API:

    MethodEndpointPurpose
    GET/api/registry/connectionsList connection definitions
    GET/api/registry/connections/{id}Fetch one definition
    POST/api/registry/connectionsRegister a definition (needs a Model)
    PUT/api/registry/connections/{id}Update a definition
    DELETE/api/registry/connections/{id}Remove a definition
  2. Consumption. The Connection Wizard lists every registered definition as a creatable kind and renders its connectionSchema and credentialSchema as wizard steps. Register your definition and it appears in the wizard automatically - no UI changes required.

  3. Lifecycle. Registration drives the default connection state machine, which implements these transitions: discovered β†’ registered | ignored, registered β†’ connected | ignored, connected β†’ disconnected | deleted, and disconnected β†’ connected | deleted. Connecting persists the Connection and its credential. No server code is required - add a kind-specific action only when the kind needs a reachability probe before it may advance to connected (Grafana and Prometheus verify their endpoint; Kubernetes has a bespoke machine altogether). Keep the transitionMap you author in step with this machine: it is the copy the UI shows for each transition.

  4. Seeding. Most Connections are created by a user through the wizard. A few, though, describe something Meshery itself uses, and Meshery seeds those for itself at boot so they are present out of the box - see System-owned Connections below.

System-owned Connections

Meshery generates Models and Components from sources it reaches on its own: it pulls packages from Artifact Hub and reads manifests from GitHub repositories. Those sources are Connections too, and Meshery seeds them for itself during boot-time seed-data initialization so a user finds them already present rather than having to create them by hand.

Seeding runs at the end of model registration (SeedComponents β†’ SeedConnections in server/models/), which is also when every path that rebuilds the registry - server start, database reset, hard reset - picks it up. Because the two reset paths drop every table before rebuilding, they re-migrate the full system-table set from one shared list (models.SystemDatabaseModels, applied via AutoMigrateSystemTables) rather than a hand-maintained subset, so the tables a seeded Connection and the Connections page read from - including environment_connection_mappings - always exist after a reset. It is driven entirely by the registry: the set of Connections seeded is derived from the registered connection definitions, never from a list of kinds written into the server. A definition is seeded when both of the following hold:

  1. Meshery already sources content through the kind - it holds a registrant Connection of that kind that owns registered Models, the host those Models, and the Components and Relationships beneath them, are registered under. This is what separates Artifact Hub and GitHub from Kubernetes, Grafana and Prometheus: the latter describe resources a user brings, and would be meaningless as empty, endpoint-less rows. Registered Models are required rather than merely any registered entity, because registering a connection definition through POST /api/registry/connections creates a registrant of whatever kind the request body names; requiring Models keeps the rule out of reach of request input.
  2. The kind works anonymously - its credentialSchema marks nothing as required. A seeded Connection is owned by the system and carries no credential, so a kind that cannot be used without one is never seeded.

A seeded Connection takes its name, type and subType from its definition, which is the authoritative identity for the kind. Three properties are deliberately left alone:

  • status is not re-asserted. The definition’s status is the state a new Connection starts in; once the Connection exists its state belongs to the state machine, so seeding never undoes a user who connected or ignored it.
  • A credential you attach is preserved. A kind is only seedable because its credentialSchema marks nothing as required, which is exactly what makes attaching one optional rather than impossible - an Artifact Hub API key, or a GitHub token that raises your API rate limit. Seeding never clears credentialId, so a credential you add through the wizard survives every subsequent restart.
  • A user’s own Connections are never touched. Seeding only ever writes the registrant rows Meshery created itself, so a Connection you created of the same kind is left exactly as you left it.

Seeding is idempotent across restarts, and it never adds a Connection row. It only ever rewrites rows that model registration already created, and it writes one only when that row does not already match its definition, so a restarted server performs no seeding work at all.

Advanced: customizing the wizard

The generic flow - choose β†’ configure β†’ credential β†’ review β†’ done, all derived from your schemas - covers most Connections. When a Connection needs bespoke steps (Kubernetes, for example, imports clusters from a kubeconfig and offers a MeshSync deployment-mode step), register a connection extension in the Meshery UI at ui/components/connections/wizard/registry.ts.

An extension matches a Connection by kind (optionally narrowed by type/subType) and may override any step; the most specific match wins, and any step left unset falls back to the generic default:

  • detailsStep, credentialStep, registerStep, receiptStep - override individual steps. Set credentialStep: null to remove the credential step (Kubernetes carries its credential inline as a kubeconfig).
  • postConfigSteps - extra steps appended after registration; these also drive the wizard’s configure mode for an already-registered Connection.

Each step implements a small contract - an id and label, a Component to render, and optional canProceed, onNext, nextLabel, and hidden hooks. Use the existing kubernetesExtension as a worked example, and see Contributing to the Meshery UI for building and testing UI changes.

AI provider Connections

AI inference providers use Meshery’s existing Connection and Credential resources. This keeps endpoint configuration, lifecycle, ownership, and secret handling in the same system as other integrations. Do not add an AI-only configuration store or registration endpoint.

Identity and metadata

Use these canonical identity values for AI provider Connection definitions:

FieldValueMeaning
kindaiProviderGroups AI inference provider Connections in the wizard.
typeaiClassifies the service.
subTypeA lowercase provider slug, such as openai, anthropic, ollama, or localaiIdentifies the provider implementation.

Any wizard extension or provider-definition lookup must match the full identity tuple (kind, type, and subType). Multiple provider definitions share kind: aiProvider; matching on kind alone can select another provider’s form and schema.

The Connection’s metadata contains non-secret endpoint and inference settings. A definition must declare these camelCase fields in its connectionSchema:

Metadata fieldRequirementContract
baseUrlRequiredAbsolute provider API URL. Cloud and self-hosted endpoints must use HTTPS with certificate verification enabled; never disable TLS verification. Permit HTTP only for hostingMode: local with localOnly: true when the endpoint host is loopback (localhost, 127.0.0.1, or ::1). Supply a provider default only when the provider has a stable default endpoint.
defaultModelRequiredModel identifier sent for inference when a request does not choose a model.
timeoutSecondsRequiredPositive request timeout. The server may impose a stricter deployment-wide maximum.
hostingModeRequiredcloud, local, or selfhosted. This describes where the endpoint runs; it is not inferred from its URL or provider name.
localOnlyRequiredBoolean policy declaration. true means requests and prompt data must remain within the operator’s configured trust boundary; do not silently fall back to a cloud service.
healthSystem-managed, optional until first checkSanitized health summary: lastCheckedAt, lastSuccessAt, and a stable reasonCode. Clients cannot set it. Never put raw provider responses, prompts, credentials, or unfiltered error text here.

Provider-specific, non-secret options may be added only in the schema definition for that provider. They must use camelCase, be documented there, and must not duplicate secret material. credentialId is a reference to the existing credential association, not a value in metadata.

Credentials and provider classes

Credentials use the existing Meshery Credential resource and the provider’s credentialSchema. Credential fields are stored only in the credential’s secret payload; the Connection stores a reference to the Credential, never a key or token.

Provider classCredential requirementExamples
Hosted cloud APIRequiredOpenAI, Anthropic, and hosted Azure OpenAI endpoints require their provider-issued authentication.
Local inference or self-hosted endpointOptional, based on endpoint authenticationOllama and LocalAI can run without credentials. If authentication is enabled, associate a Credential; its fields are optional in the definition for deployments that do not enable auth.

The definition must make this distinction visible in credentialSchema: mark authentication fields required for providers that always require them; keep them optional for providers that can run anonymously; omit the credential schema only when that provider cannot accept credentials. A self-hosted endpoint that requires authentication follows the same Credential path as a cloud endpoint.

An anonymous registration must leave the Connection’s credential association empty and must not create a blank Credential record. Optional fields in credentialSchema alone do not make the current wizard flow credential-free: the wizard and registration action must skip both credential creation and association when the user chooses anonymous access. When credentials are supplied, create and associate the normal Credential.

Raw keys and tokens are write-only inputs. After save, credential responses must omit secret values, and logs, error messages, prompts, model context, generated Designs, and Connection metadata must not contain them. AI request code must resolve credentials through the existing credential-secret helpers, not index the persisted secret map directly.

Current behavior: write-only credential responses are not implemented yet. The Local provider’s credential detail and list APIs currently serialize stored credentials with their secret field. This PR defines the requirement; it does not change the existing API behavior. Track and complete the required API and response-redaction work in #23096 before shipping AI provider clients. Remote provider response behavior must also be covered by that work.

Before redacting existing credential responses, migrate current consumers that read returned secrets. In particular, connection verification must pass the selected credentialId to the server and let the server resolve the secret for the verification operation; it must not send the secret back to the UI. Complete this consumer migration before enforcing write-only responses, so existing credential reuse continues to work.

Health and lifecycle

Use the existing Connection states; do not introduce AI-specific status values. A new Connection starts registered. The provider definition must supply a verification action, and the wizard must not mark the Connection connected until that check succeeds. A successful check moves registered or disconnected to connected; a failed reachability or authentication check moves registered or connected to disconnected; a later successful check restores connected. Declare these transitions in the AI provider definition’s transitionMap, including registered to disconnected because the default Connection machine does not include that edge. Use not found only when the provider definitively reports that the configured resource no longer exists, not for timeouts or rejected credentials. Health checks update the Connection status and the sanitized, system-managed metadata.health fields above. They must never log request bodies, prompts, authorization headers, or raw provider error bodies.

When localOnly is true, the server must fail closed if it cannot use the declared local endpoint. It must not route requests to a cloud endpoint or retry through a remote provider.

Registration and schema work

The provider Connection definition is a Meshery Model construct and must be defined in meshery/schemas before server or UI implementation. Add the canonical identity, metadata properties, and provider-specific connectionSchema/credentialSchema there, generate the supported consumers, and run the schemas validator and consumer audit. The implementation then consumes those generated contracts. There is no AI-specific API contract to add.

Register the definition through the Registry connection-definition flow (/api/registry/connections). Create and manage a user’s configured provider through the existing /api/integrations/connections and /api/integrations/credentials resources. The older /api/integrations/connections/register flow is not the definition registry and must not become a separate AI registration path. Any new or changed HTTP fields or operations still require a schemas API definition and generated client before Meshery server/UI work.

Existing AI proposals

  • PR #18032, which proposes an AI config endpoint, should be reworked to use the generated Connection and Credential APIs or closed. A parallel endpoint would create a second source of truth.
  • PR #18696, which proposes environment-variable provider configuration, may use variables as a development bootstrap only. They are not persisted user configuration or a production fallback. Provider settings and secrets in deployed use belong to Connections and Credentials.
  • The Registry route migration in #17965 and #17966 does not change this ownership boundary: register definitions through the canonical Registry route, and manage configured Connections and Credentials through their integration resources.

Authoring best practices

  1. Use camelCase for property names, matching the rest of Meshery’s schemas.
  2. Keep the transitionMap consistent with the documented Connection states; do not invent states.
  3. Mark only genuinely required fields as required in connectionSchema, and omit credentialSchema when no secret is needed.
  4. Start from a shipped definition rather than from scratch.
  5. Provide both svgColor and svgWhite icons so the kind renders well on light and dark backgrounds.

Contribute your Connection

Submit a pull request to the Meshery repository adding your connection definition to its Model’s connections/ folder, so every user benefits from the new Connection kind. Follow the contribution gitflow and sign off your commits.