Registering a Connection

A Connection is how Meshery tracks and manages a resource - a Kubernetes cluster, a Grafana instance, a Prometheus server, and many more. The Connection Wizard is the guided, in-UI way to register a new Connection or reconfigure an existing one, without hand-editing YAML or memorizing API payloads.

This guide covers creating and updating Connections with the wizard. For what a Connection is, the states it moves through, and how it is managed over time, see the canonical references:

Connections - what Connections are and their full state lifecycle.
Credentials - how Meshery authenticates to a Connection.
Managing Connections - operating Connections after they are registered.

Discovered vs. manually registered Connections

Meshery learns about Connections two ways. Managed Connections (for example, the resources inside a Kubernetes cluster) are auto-discovered by MeshSync and arrive already in the Discovered state. Unmanaged Connections (for example, a standalone Grafana or Prometheus) are added by you. The Connection Wizard is how you do the latter - and how you bring a Kubernetes cluster under management in the first place.

Before you begin

A running Meshery deployment. See the Quick Start if you do not have one yet.
Permission to add Connections. The wizard is permission-gated: adding a Kubernetes cluster requires the add cluster permission, and other Connection kinds require the connect metrics permission. If you lack both, the Create Connection button is disabled. See Roles and Permissions.
For an authenticated Connection (most Grafana/Prometheus instances), the access token or credential you intend to use. You can paste it during the wizard or reuse an existing Credential.

Launching the Connection Wizard

Open the Connections page in Meshery (Lifecycle → Connections).
Click Create Connection.

The wizard opens as a modal. The set of Connection kinds you can create is driven by the connection definitions registered in your Meshery Server’s Registry. Out of the box this includes Kubernetes, Grafana, and Prometheus; your deployment may offer more. If a kind you need is missing, a contributor can add it - see Contributing a Connection.

Creating a Connection

Most Connections follow the same generic flow. Each step is rendered from the connection definition itself, so the exact fields you see depend on the kind you choose.

Choose Connection. Pick the kind of Connection to create (for example, Grafana). Kinds you do not have permission to add are shown but cannot be selected.
Configure Connection. Fill in the Connection’s details - typically the endpoint URL and an optional friendly name. Required fields are validated before you can continue. For a Grafana Connection, for instance, you supply the Grafana endpoint (e.g. http://grafana.example:3000).
Associate Credential. Provide the secret Meshery will use to authenticate. You can either:
- Reuse an existing credential - the list is filtered to credentials that match the Connection’s kind, or
- Create a new credential - enter the token, API key, or username:password and give it a name (it defaults to the Connection’s name).
You may also choose to skip credential verification, which registers the Connection without first probing reachability - useful when the target is not reachable yet but you still want it on record. This step is omitted entirely for kinds that do not define a credential (and for Kubernetes, whose kubeconfig is its credential - see below).
Review & Create. Confirm the summary and click Create Connection. Meshery registers the Connection and immediately attempts to connect to it.
Done. On success, the Connection becomes a first-class resource, listed in the Connections table and ready to use.

What 'Create' actually does

Creating a Connection performs two transitions in sequence: it registers the Connection (recording it and its credential) and then connects to it (verifying reachability and beginning management). A reachable Connection lands in the Connected state; if Meshery cannot reach it - or you skipped verification - it remains Registered. You can drive further transitions later from the Connections table.

Credentials

Credentials entered in the wizard are persisted as first-class, named Credentials, encrypted at rest, and reusable across other Connections. Meshery never exposes them in logs or API responses. To learn how Meshery interprets a credential’s secret (Basic auth vs. bearer token vs. anonymous), see Credentials and the Telemetry authentication note.

Importing a Kubernetes cluster

Kubernetes uses a dedicated flow because a single kubeconfig can describe many clusters and its kubeconfig also serves as its credential.

Choose Connection → Kubernetes.
Import Kubeconfig. Upload a kubeconfig file. Meshery parses it and lists the contexts it contains, indicating which are reachable - nothing is persisted yet.
Select contexts. Choose which contexts to import. For each, you can override the Connection name and choose a MeshSync deployment mode.
Review Import. Confirm your selection and import. Meshery creates one Connection per selected context and reports the outcome, grouped into connected, registered, ignored, and errored buckets.

Each imported cluster is created as a Kubernetes Connection that MeshSync keeps in sync. From there, Meshery can deploy and operate workloads, visualize the cluster, and more. See Managing Connections. If the cluster already runs workloads you did not deploy through Meshery, see Bringing Existing Infrastructure Under Meshery Management for what to evaluate before importing and how discovery treats pre-existing resources.

Who can access an imported cluster?

A Kubernetes Connection is owned by the user who imported it and is private until you explicitly share it - by assigning it to an Environment and that environment to a Workspace. See the sharing FAQ under Managing Connections.

MeshSync deployment mode

When you import or reconfigure a Kubernetes cluster, you choose how MeshSync - the component that keeps Meshery’s view of the cluster’s resources up to date - runs:

Operator - installs the Meshery Operator into the cluster. MeshSync runs in-cluster and streams resource changes to Meshery in real time.
Embedded - runs MeshSync from within Meshery Server. Nothing is installed into the cluster; discovery happens out-of-cluster. This is the default.

Switching the mode later makes Meshery redeploy MeshSync accordingly (see Updating a Connection). For the behavioral trade-offs between the two modes - cluster footprint, permissions, network requirements, and what each mode gives up - and for every other setting of these components, see Configuring Meshery Operator, MeshSync, and Broker.

Updating a Connection

The wizard also reconfigures an already-registered Connection. From the Connections table, open a Connection’s action menu and choose Configure. The wizard opens in configure mode and presents only the post-registration steps relevant to that kind.

For a Kubernetes Connection, this is where you change the MeshSync deployment mode. Selecting a different mode and clicking Apply makes Meshery undeploy MeshSync and redeploy it in the newly selected mode (Operator or Embedded) for that cluster.

Changing a Connection's state

Configuring a Connection is distinct from transitioning its state (Connected, Ignored, Disconnected, and so on). State transitions - and the rules governing which are allowed - are driven by the connection definition and performed from the status control on the Connections table. See States and the Lifecycle of Connections.

Using Connections for Telemetry

Grafana and Prometheus Connections you register with the wizard power Meshery’s Telemetry views. Once such a Connection reaches the Connected or Registered state, it becomes selectable in the Telemetry connection picker, where you can:

Browse and render your existing dashboards - see Grafana Dashboards.
Explore metrics and save PromQL panels - see Prometheus Metrics.

Registering Connections from the CLI

Prefer the terminal? mesheryctl can create, list, view, and delete Connections too. See mesheryctl connection.

Connections - concepts and state lifecycle.
Configuring Meshery Operator, MeshSync, and Broker - tuning the components that keep an imported cluster in sync.
Credentials - authentication for Connections.
Environments and Workspaces - grouping and sharing Connections.
Managing Connections - lifecycle operations.
Contributing a Connection - add a new Connection kind to the wizard.

Discussion Forum

Don't find an answer to your question here? Ask on the Discussion Forum.

Overview

Managing Existing Infrastructure