Skip to main content
Nexus BYOC is available only on Enterprise plans.
For architecture, see the Nexus BYOC overview. For data residency and limits, see Data residency and limits.

​
Prerequisites

Before deploying Nexus BYOC, ensure you have the following tools installed on the machine that runs the install: You also need:
  • The CLI for your cloud provider:
  • A dedicated cloud account with admin-level permissions, used only for this deployment:
    • AWS: a dedicated account with AdministratorAccess. The installer creates IAM roles and policies, so PowerUserAccess is not sufficient.
    • GCP: a dedicated project with roles/owner and billing enabled. The installer creates IAM service accounts and bindings, so roles/editor is not sufficient.
    • Azure: a dedicated subscription with Owner. The installer creates managed identities and role assignments, so Contributor is not sufficient.
  • A Pinecone API key from the Pinecone console.
  • A Pinecone Enterprise plan (required for BYOC access).
  • A generation-LLM key. Every model Nexus uses is BYOM and configurable through the model catalog: generation, embedding, and rerank. The catalog is backed by LiteLLM, so you can bring any model any LiteLLM-supported provider offers, referenced by its LiteLLM provider/model identifier. The shipped defaults route generation to Google Gemini (get a key from Google AI Studio) and route embedding and rerank to Pinecone-hosted models (no extra key). You can repoint any tier at a different provider (including endpoints inside your own boundary), each with its own key. Which model each call reaches determines where the content of that call goes. See Data flows and residency.
  • A Pulumi state backend (either Pulumi Cloud or local state via pulumi login --local).
  • Sufficient cloud quota for the resources (the setup wizard validates this).
Confirm these environment inputs before you start:
  • Region and three availability zones (AZs). Deploy across three AZs, the supported high-availability shape. The generation-model provider you choose must be available in the region.
  • A spare private IP range (RFC 1918, /16 to /20) that does not overlap your existing networks. This becomes the Nexus virtual network.
  • Where your source data lives. Know where your corpus resides so you can stage it into a context after install.
  • Egress paths. Nexus makes outbound connections for the control-plane callback, metrics and traces, container image pulls, and calls to the inference models you configure. What content those model calls carry depends on how you configure your models. See Data flows and residency.
If you install any new tools, open a new terminal session before proceeding so that your shell picks up the updated PATH and environment.

​
1. Deploy

To deploy Nexus BYOC, follow these steps.
1

Authenticate

The setup script checks your credentials but does not log you in, so authenticate to your cloud and to Pulumi first.
If you use the local Pulumi backend, choose a passphrase for encrypting stack secrets and export it as PULUMI_CONFIG_PASSPHRASE. Every pulumi command needs it.
2

Run the setup wizard

Clone the deployment repository and run the bootstrap script from the clone. The generated project is created next to the clone and depends on it.
Use --cloud aws or --cloud azure for the other clouds, and --stack-name <name> to name the Pulumi stack (default: prod).The script selects your cloud provider, checks that required tools are installed, verifies your cloud credentials, prompts for the project directory and name, then launches an interactive wizard that collects your configuration, validates your quotas, and generates a Pulumi project in an adjacent directory (default: pinecone-nexus-byoc). No cloud resources are created during this step.
The wizard prompts you for the following:
After completing the wizard, a Pulumi project is generated in your project directory. To change configuration later, edit Pulumi.<stack>.yaml and run pulumi up.
3

Deploy the infrastructure

Deploy the generated Pulumi project to create your cloud resources:
Pulumi shows a preview of all resources to be created. Confirm to proceed. Provisioning time depends on the cloud:When complete, the output displays:
  • The update_kubeconfig_command for configuring cluster access.
  • Your BYOC environment name.
  • Two workspace console links, printed once the first-run default workspace reaches Ready:
    • nexus_default_workspace_data_console_url: the workspace console for the default workspace, served from your deployment (where you work with contexts and run queries).
    • nexus_default_workspace_control_console_url: the Pinecone Console page for that workspace.
The first pulumi up creates a default workspace automatically and waits for it to become ready before printing the links. Later pulumi up runs never recreate or modify it.
The deployment creates the following in your cloud account:The cluster comes up small and then autoscales to a steady-state footprint of roughly 20 nodes across several node pools spread over the three AZs. See Cluster footprint for the per-pool breakdown.
4

Verify the deployment

Configure kubectl using the update_kubeconfig_command from the deployment output:
Cluster access is for administrative tasks like viewing operations and troubleshooting. Everyday work (creating contexts, curating sources, and running queries) uses the Nexus console, CLI, or API.Verify all components are running:
All pods should show Running status. If any are in Pending or CrashLoopBackOff, see Troubleshooting.

​
2. Use

Once your deployment is up and the default workspace is ready, you work with Nexus the same way you would in the managed service. For the end-to-end lifecycle (create a context, stage sources, curate, and query with KnowQL), see the Nexus quickstart. Two things are specific to BYOC:
  • Point your client at your own workspace host. Instead of the Pinecone-hosted endpoint, use your deployment’s workspace host, the base of nexus_default_workspace_data_console_url from the deployment output. For the CLI, pass it as --api-url:
    Authentication uses your Pinecone API key, and the tenancy boundary is the workspace’s Pinecone project.
  • A default workspace is created on the first pulumi up. The install creates it automatically and prints its data console URL (served from your deployment) and its Pinecone Console URL. Later pulumi up runs never recreate or modify it.

​
3. Manage

Deploying a BYOC environment creates an internal project named __SLI__ in your organization. Pinecone uses it to enforce SLAs for your BYOC environment. Do not modify or delete it.

​
Operations and upgrades

Pinecone uses a pull-based model for cluster operations:
  1. When upgrades, scaling, or maintenance are needed, Pinecone queues operations in the control plane.
  2. An agent running in your cluster (deployed automatically during setup) continuously pulls pending operations.
  3. Operations execute locally within your cluster.
  4. Status is reported back to Pinecone for monitoring.
This model ensures Pinecone never needs direct access to your infrastructure. All communication is outbound from your cluster. A deployment is pinned to two independent image tags that roll separately: pinecone-version (the Pinecone Database images) and nexus-version (the Nexus images). The two pins are unrelated. Bumping one does not touch the other. Pinecone manages upgrades in the background. To trigger one manually, set either pin (or both) to your target version (for example, main-abc1234) and re-run pulumi up:

​
Monitoring

You can monitor your deployment through multiple channels:
View workspace and index metrics in the Pinecone console. Control plane operations and metrics work regardless of your network access mode.
To use Prometheus, configure your monitoring tool within your VPC to scrape metrics from the cluster. Your Prometheus instance must have network access to the BYOC VPC. The deployment output includes the metrics endpoint URL and port.
Cluster operations are persisted as Kubernetes CRDs for compliance and auditing:

​
Cleanup

Delete all Nexus workspaces before destroying the cluster. Resources cannot be properly terminated if the cluster is destroyed first.
To destroy your deployment:
If deletion-protection is enabled (the default), you must either disable it in Pulumi.<stack>.yaml and run pulumi up, or manually delete the protected storage and database resources via the cloud console before running pulumi destroy.

​
Troubleshooting

The setup wizard validates cloud quotas before deployment. If checks fail:
If pulumi up fails partway through:
On AWS, the slowest single step is VPC endpoint service private DNS verification: roughly 15 minutes of Waiting for domain verification (pendingVerification) polling is normal, not a hang. Let it finish.
Ensure your cloud credentials match the account where the cluster is deployed:
The first-run default workspace is created asynchronously and becomes ready only once the Nexus services in your deployment are up. If pulumi up times out waiting for it, re-run pulumi up once the cluster pods are Running. If it remains stuck, contact Pinecone support.
For additional help, see the GitHub Issues for the deployment repository.