BYOC On-Premise¶

BYOC On-Premise lets a customer bring an existing Kubernetes cluster and use it as the deployment target for your Product. Omnistrate treats this target as the byoc-onprem provider with the on-prem deployment region.

The customer owns the Kubernetes cluster, nodes, storage, network routing, and endpoint exposure. Your generated control plane operates deployments in that cluster through your product dataplane agent.

BYOC On-Premise is configured as a BYOC deployment Plan. Set up the provider side the same way you would for other BYOC Plans, then pass --cloud-provider=byoc-onprem when creating customer onboarding instances and product deployments. For the shared BYOC flow, see BYOC cloud accounts. For the Plan schema, see deployment schema.

This mode is different from an Air-gapped installer. In BYOC On-Premise, the customer stays connected to your generated control plane. For air-gapped or fully disconnected environments, use the On-Premise installer model instead.

Architecture¶

The product dataplane agent runs in the customer cluster and opens outbound mTLS/gRPC agent connections to your control plane. The same agent connection pattern is used for the Manager Service, Infra Metadata Manager, and Monitoring Service.

The customer does not need to expose the Kubernetes API server publicly. The cluster needs outbound access to your control plane endpoints, plus any image registries and Helm chart registries required by your Plan and deployment-cell amenities.

Application traffic is separate from control-plane traffic. The customer decides whether product endpoints are private-only, reachable through a corporate network, or exposed through a public IP or load balancer.

Before You Start¶

Confirm the customer cluster has the baseline requirements for your product:

If your product needs cluster-level components, configure them as deployment-cell amenities, or have the customer install equivalent prerequisites before deploying product instances. Examples include ingress controllers, cert-manager, monitoring, endpoint checks, logging, and custom Helm packages. The BYOC On-Premise install kit installs the dataplane agent; amenities and product workloads are handled after the agent connects. See Deployment Cell Amenities.

End-to-End Walkthrough¶

This walkthrough uses PostgreSQL as the example product. The same sequence applies to other products that support byoc-onprem.

1. Provider prepares the Plan¶

Build and release a Plan that can deploy to customer-owned clusters. The product instance later selects BYOC On-Premise with --cloud-provider=byoc-onprem.

name: BYOC OnPrem Simple PG Test
deployment:
  byoaDeployment:
    AwsAccountId: '<aws-account-id>'
    AwsBootstrapRoleAccountArn: 'arn:aws:iam::<aws-account-id>:role/omnistrate-bootstrap-role'

services:
  - name: postgresChart
    network:
      ports:
        - 5432
    endpointConfiguration:
      postgresEndpoint:
        host: "$sys.network.internalClusterEndpoint"
        ports:
          - 5432
        primary: true
        networkingType: INTERNAL

BYOC On-Premise does not provision nodes; the customer-managed Kubernetes cluster is the deployment target. The Plan should define the product endpoints, parameters, persistent volumes, metrics, dashboards, and upgrade paths that apply to the customer deployment. This walkthrough uses an internal endpoint.

2. Create the BYOC On-Premise onboarding instance¶

The customer onboarding instance represents one customer-owned Kubernetes cluster. Passing --cluster-name (instead of a cloud-provider account flag such as --aws-account-id) selects the BYOC On-Premise path.

Create a working directory first. The onboarding command automatically downloads the generated install kit into the current directory.

mkdir -p dp-install-kit
cd dp-install-kit

omnistrate-ctl account customer create \
  --service=<service-name> \
  --environment=<environment-name> \
  --plan=<plan-name> \
  --cluster-name=<customer-cluster-name> \
  --cluster-description="Customer production Kubernetes cluster"

If you create the onboarding instance on behalf of a customer, add --customer-email=<[email protected]>.

Save the returned customer onboarding instance ID, for example instance-abc123. The command does not wait for the onboarding instance to become READY. After the dataplane agent connects, you pass the same onboarding instance ID as --customer-account-id in the deployment command.

3. Install the dataplane agent on the target cluster¶

Extract the kit and confirm kubectl targets the intended customer cluster:

# If the kit was downloaded elsewhere, copy or move it into this directory first.
tar xf byoc-onprem-install-kit-<account-config-id>.tar
kubectl config current-context

Run the installer against the current Kubernetes context:

./install.sh --non-interactive

The installer creates the dataplane-agent resources in the cluster. Amenities and product workloads are installed later by your control plane.

Test your deployment¶

If you do not have a customer cluster yet and want to validate the flow end to end, the same install kit can spin up a local or single-node test cluster.

For a fully local smoke test, create a k3d cluster:

./install.sh \
  --create-k3d-cluster <cluster-name> \
  --non-interactive

If your test host has a public IP and you want to validate a public endpoint Plan, create a single-node K3s cluster on that host and advertise the public IP:

PUBLIC_IP=<node-public-ip>

./install.sh \
  --create-k3s-cluster <cluster-name> \
  --k3s-node-external-ip "${PUBLIC_IP}" \
  --non-interactive

For a public endpoint Plan, use the external cluster endpoint in the Plan instead of the internal one:

services:
  - name: postgresChart
    network:
      ports:
        - 5432
    endpointConfiguration:
      postgresEndpoint:
        host: "$sys.network.externalClusterEndpoint"
        ports:
          - 5432
        primary: true
        networkingType: PUBLIC

In production, customers install into their existing Kubernetes cluster and skip the --create-k3d-cluster / --create-k3s-cluster flags.

4. Verify the account configuration¶

After the agent connects to your control plane, the BYOC On-Premise account configuration moves to READY.

omnistrate-ctl account customer describe <customer-account-instance-id>

Continue when account_status is READY.

5. Deploy a product instance¶

Create the product instance and pass the BYOC On-Premise onboarding instance ID as --customer-account-id.

For the PostgreSQL example, create a parameter file:

{
  "pgPassword": "change-me",
  "pgDatabase": "appdb"
}

omnistrate-ctl instance create \
  --service=<service-name> \
  --environment=<environment-name> \
  --plan=<plan-name> \
  --version=latest \
  --resource=postgresChart \
  --cloud-provider=byoc-onprem \
  --region=on-prem \
  --customer-account-id=<customer-account-instance-id> \
  --param-file=./params.json \
  --wait

Verify the instance from your control plane:

omnistrate-ctl instance describe <instance-id>
omnistrate-ctl instance list-endpoints <instance-id>

Verify the workload in the customer cluster with the same Kubernetes context used to run install.sh. Restrict the query to the instance namespace:

kubectl get all -n <instance-id>
helm list -n <instance-id>

6. Operate the instance¶

After the instance is running, lifecycle operations continue through your control plane:

omnistrate-ctl instance dashboard <instance-id>
omnistrate-ctl instance version-upgrade <instance-id> --target-version=<version>
omnistrate-ctl instance delete <instance-id>

The customer can still inspect and operate their Kubernetes cluster with their own tools.

omnistrate-ctl account customer install-kit <customer-onboarding-instance-id>

Limitations¶

• The customer cluster must have outbound connectivity to your control plane.
• BYOC On-Premise is not for fully air-gapped environments; use the Air-gapped installer for that model.
• Each customer onboarding instance maps to one Kubernetes cluster.
• Endpoint reachability depends on the customer's DNS, firewall, load balancer, and routing configuration.

Related Guides¶

• BYOC cloud accounts
• Deployment Cell Amenities
• BYOC PrivateLink
• Air-gapped installer