Plugin SDK¶

The SDK is the contract between a plugin and CloudSlash core. It is intentionally small: plugins collect observations, while CloudSlash owns the graph, findings, cost, carbon, policy, plans and execution.

Module: github.com/DrSkyle/cloudslash-plugin-sdk

Packages¶

Hosted source contract¶

A hosted or customer-runner source is an out-of-process Go binary using gRPC over TLS. It must ship:

• cmd/hosted — the entrypoint built by cs plugin host <source> --run;
• a --manifest mode that prints one JSON document;
• a read-only v3.Source with Capability, Preflight and Scan;
• ConnectionMethods() describing the connection fields and permissions.

The --manifest document has:

{
  "plugin_name": "cloudslash-plugin-example",
  "version": "2.0.1",
  "capabilities": ["read.inventory"],
  "v3_capabilities": { "read.inventory": { "...": "..." } },
  "connection_methods": [ { "...": "..." } ]
}

The capability must include connection_schema_digest, computed by v3.ConnectionMethodsDigest(methods). CloudSlash recomputes the same digest and the manifest digest from name, version, endpoint and capabilities; both are pinned at registration and preflight.

Generate the current template¶

cs plugin create my-source --hosted --sdk-path cloudslash/sdk

This writes the same project Plugin Studio uses:

• main.go — local ./source-plugin entrypoint;
• cmd/hosted/main.go — entrypoint built by cs plugin host;
• internal/hosted/hosted.go — shared TLS/gRPC server and --manifest export;
• source/source.go — capability, ConnectionMethods(), preflight and collection seam;
• tests, README and Makefile.

The generated ConnectionMethods() and setup-mode examples are commented so you can add, remove or replace fields and permissions for your provider. The template is a starter, not a fixed schema.

Versions¶

The plugin manifest version is the source of truth. cs plugin host injects it into the hosted entrypoint with -X main.version=<version>. Bump the manifest when you release; the registry, self-hosted listing and connection all follow. Never hardcode a hosted release version.

Connection methods¶

Each method is data:

v3.ConnectionMethod{
    ID: "provider-config",
    Title: "Provider access",
    Instructions: "Create a read-only credential in the provider.",
    Permissions: []string{"read:inventory"},
    ReadOnly: true,
    Fields: []v3.ConnectionField{
        {Key: "endpoint", Label: "Endpoint", Type: "text", Required: true, MaxLength: 512},
        {Key: "token", Label: "Token", Type: "secret", Required: true, MaxLength: 512},
    },
}

The customer can record a subset of permissions; the credential or role still decides actual access. Mutation methods are rejected. Add, remove or replace fields and permission names for your system; do not assume IAM, SSH, a database URL, or any provider-specific flow.

Setup pages¶

An optional method can declare:

SetupURL:  "https://plugins.example.com/setup",
SetupMode: "return", // "return" or "console"

return means the setup page performs the provider work and returns a finished connection. Horizon opens it with cloudslash_state and cloudslash_return; the page returns ?cloudslash_setup=<base64url(JSON)> or POSTs the same payload to /v1/connections/setup-plugin-callback from provider automation such as a CloudFormation custom resource. The customer only reviews and approves inside the plugin page. console opens a provider console and keeps the reviewed field form.

A setup_url may contain CLOUDSLASH_STATE and CLOUDSLASH_RETURN tokens. Horizon substitutes them before opening the page; otherwise it appends cloudslash_state and cloudslash_return. This lets the plugin send the customer straight to a provider quick-create page.

The bundled AWS plugin's setup URL is a prefilled CloudFormation review page; the template lives in the plugin's setup/ directory, is published to S3 because CloudFormation requires an S3 TemplateURL, and creates the role and callback Lambda in the customer's AWS account. The publisher's bucket only hosts the public template. The scaffold emits a setup/ directory with commented provider examples. The same pattern works for GCP, Azure, Kubernetes, PostgreSQL, Git, SaaS, bare metal, or an internal API: the plugin author supplies the provider template, and the customer approves it in their own environment.

See Build a plugin and Self-host plugins.