GraphQL Mutations

Mutations are write operations that modify the state of Meshery resources. All mutations require authentication.

Operator Management

Change Operator Status

Deploy, undeploy, or modify the status of Meshery Operator in a Kubernetes cluster.

mutation ChangeOperatorStatus($input: OperatorStatusInput!) {
  changeOperatorStatus(input: $input)
}

Variables:

{
  "input": {
    "targetStatus": "ENABLED",
    "contextID": "connection-uuid"
  }
}

OperatorStatusInput:

targetStatus

Status

required

Desired operator status:

ENABLED - Deploy and enable the operator
DISABLED - Disable the operator
PROCESSING - Processing state
UNKNOWN - Unknown state

contextID

string

required

Kubernetes context/connection ID where the operator should be deployed

Response:

{
  "data": {
    "changeOperatorStatus": "ENABLED"
  }
}

Example (Deploy Operator):

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation ChangeOperator($input: OperatorStatusInput!) { changeOperatorStatus(input: $input) }",
    "variables": {
      "input": {
        "targetStatus": "ENABLED",
        "contextID": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
  }' \
  http://localhost:9081/api/system/graphql/query

Example (Undeploy Operator):

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation ChangeOperator($input: OperatorStatusInput!) { changeOperatorStatus(input: $input) }",
    "variables": {
      "input": {
        "targetStatus": "DISABLED",
        "contextID": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
  }' \
  http://localhost:9081/api/system/graphql/query

Adapter Management

Change Adapter Status

Deploy or undeploy service mesh adapters (Istio, Linkerd, Consul, etc.).

mutation ChangeAdapterStatus($input: AdapterStatusInput!) {
  changeAdapterStatus(input: $input)
}

Variables:

{
  "input": {
    "targetStatus": "ENABLED",
    "targetPort": "10000",
    "adapter": "meshery-istio"
  }
}

AdapterStatusInput:

targetStatus

Status

required

Desired adapter status:

ENABLED - Deploy and enable the adapter
DISABLED - Disable the adapter
PROCESSING - Processing state

targetPort

string

required

Port on which the adapter will be deployed

adapter

string

required

Adapter name:

meshery-istio
meshery-linkerd
meshery-consul
meshery-nginx-sm
meshery-cilium
meshery-kuma
And others…

Response:

{
  "data": {
    "changeAdapterStatus": "ENABLED"
  }
}

Example (Deploy Istio Adapter):

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation DeployAdapter($input: AdapterStatusInput!) { changeAdapterStatus(input: $input) }",
    "variables": {
      "input": {
        "targetStatus": "ENABLED",
        "targetPort": "10000",
        "adapter": "meshery-istio"
      }
    }
  }' \
  http://localhost:9081/api/system/graphql/query

Example (Undeploy Adapter):

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation UndeployAdapter($input: AdapterStatusInput!) { changeAdapterStatus(input: $input) }",
    "variables": {
      "input": {
        "targetStatus": "DISABLED",
        "targetPort": "10000",
        "adapter": "meshery-istio"
      }
    }
  }' \
  http://localhost:9081/api/system/graphql/query

Available Adapters

Meshery supports adapters for multiple service meshes and platforms:

Service Mesh Adapters

meshery-istio - Istio service mesh (port: 10000)
meshery-linkerd - Linkerd service mesh (port: 10001)
meshery-consul - HashiCorp Consul (port: 10002)
meshery-nginx-sm - NGINX Service Mesh (port: 10010)
meshery-cilium - Cilium service mesh (port: 10012)
meshery-kuma - Kuma service mesh (port: 10007)
meshery-osm - Open Service Mesh (port: 10009)
meshery-traefik-mesh - Traefik Mesh (port: 10006)
meshery-app-mesh - AWS App Mesh (port: 10005)
meshery-tanzu-sm - VMware Tanzu Service Mesh (port: 10008)

Network Service Mesh

meshery-nsm - Network Service Mesh (port: 10004)

Mutation Examples

Deploy Multiple Controllers

You can chain mutations or run them sequentially:

mutation DeployInfrastructure(
  $operatorInput: OperatorStatusInput!
  $adapterInput: AdapterStatusInput!
) {
  # Deploy Meshery Operator
  operator: changeOperatorStatus(input: $operatorInput)
  
  # Deploy Istio Adapter
  adapter: changeAdapterStatus(input: $adapterInput)
}

Variables:

{
  "operatorInput": {
    "targetStatus": "ENABLED",
    "contextID": "connection-uuid"
  },
  "adapterInput": {
    "targetStatus": "ENABLED",
    "targetPort": "10000",
    "adapter": "meshery-istio"
  }
}

Error Handling

Mutations return errors in the standard GraphQL format:

{
  "data": {
    "changeOperatorStatus": null
  },
  "errors": [
    {
      "message": "connection not found",
      "locations": [{"line": 2, "column": 3}],
      "path": ["changeOperatorStatus"],
      "extensions": {
        "code": "CONNECTION_NOT_FOUND"
      }
    }
  ]
}

Common Error Codes

AUTHENTICATION_REQUIRED

error

Missing or invalid authentication token

CONNECTION_NOT_FOUND

error

Kubernetes connection/context not found

DEPLOYMENT_FAILED

error

Failed to deploy operator or adapter

INVALID_INPUT

error

Invalid mutation input parameters

Best Practices

Check Status Before Mutation

Before deploying or undeploying, check the current status:

# First, query current status
query {
  getOperatorStatus(connectionID: "connection-uuid") {
    status
  }
}

# Then, if needed, change status
mutation {
  changeOperatorStatus(input: {
    targetStatus: "ENABLED",
    contextID: "connection-uuid"
  })
}

Handle Async Operations

Deployments are asynchronous. Use subscriptions to monitor progress:

# 1. Trigger deployment
mutation {
  changeOperatorStatus(input: {
    targetStatus: "ENABLED",
    contextID: "connection-uuid"
  })
}

# 2. Subscribe to status updates
subscription {
  subscribeMesheryControllersStatus(connectionIDs: ["connection-uuid"]) {
    connectionID
    controller
    status
  }
}

Validate Connection First

Ensure the Kubernetes connection is valid before attempting deployments:

# Test connection via REST API first
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:9081/api/integrations/connections/{connectionId}

# Then proceed with GraphQL mutation

JavaScript Example

const deployOperator = async (contextID) => {
  const query = `
    mutation DeployOperator($input: OperatorStatusInput!) {
      changeOperatorStatus(input: $input)
    }
  `;

  const variables = {
    input: {
      targetStatus: 'ENABLED',
      contextID: contextID
    }
  };

  const response = await fetch('http://localhost:9081/api/system/graphql/query', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ query, variables })
  });

  const result = await response.json();

  if (result.errors) {
    console.error('Deployment failed:', result.errors);
    return null;
  }

  return result.data.changeOperatorStatus;
};

// Usage
const status = await deployOperator('connection-uuid');
console.log('Operator status:', status);

Python Example

import requests
import json

def deploy_adapter(adapter_name, port, token):
    query = """
    mutation DeployAdapter($input: AdapterStatusInput!) {
      changeAdapterStatus(input: $input)
    }
    """
    
    variables = {
        "input": {
            "targetStatus": "ENABLED",
            "targetPort": port,
            "adapter": adapter_name
        }
    }
    
    response = requests.post(
        'http://localhost:9081/api/system/graphql/query',
        headers={
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        },
        json={'query': query, 'variables': variables}
    )
    
    result = response.json()
    
    if 'errors' in result:
        print(f"Deployment failed: {result['errors']}")
        return None
    
    return result['data']['changeAdapterStatus']

# Usage
status = deploy_adapter('meshery-istio', '10000', 'your-token')
print(f"Adapter status: {status}")

Overview

REST API

GraphQL API

GraphQL Mutations

Operator Management

Change Operator Status

Adapter Management

Change Adapter Status

Available Adapters

Service Mesh Adapters

Network Service Mesh

Mutation Examples

Deploy Multiple Controllers

Error Handling

Common Error Codes

Best Practices

Check Status Before Mutation

Handle Async Operations

Validate Connection First

JavaScript Example

Python Example

Build docs developers (and LLMs) love

Overview

REST API

GraphQL API

​Operator Management

​Change Operator Status

​Adapter Management

​Change Adapter Status

​Available Adapters

​Service Mesh Adapters

​Network Service Mesh

​Mutation Examples

​Deploy Multiple Controllers

​Error Handling

​Common Error Codes

​Best Practices

​Check Status Before Mutation

​Handle Async Operations

​Validate Connection First

​JavaScript Example

​Python Example

Build docs developers (and LLMs) love

Operator Management

Change Operator Status

Adapter Management

Change Adapter Status

Available Adapters

Service Mesh Adapters

Network Service Mesh

Mutation Examples

Deploy Multiple Controllers

Error Handling

Common Error Codes

Best Practices

Check Status Before Mutation

Handle Async Operations

Validate Connection First

JavaScript Example

Python Example