Operator guide for Valet Dedicated 0.10.1

Private systems

A private system is a service inside your network, such as a production database, that an app can reach. You define the system and the addresses it may use in the module. An org Admin then gives an app access to it in Valet. The app gets the network path and the credentials together, and only while the Admin's approval holds.

You decide what is reachable. An Admin decides who gets it.

Define a system

Set private_systems in the module and apply it. The input holds no secret.

module "valet" {
  # ...
  private_systems = {
    shiphero-db = {
      description = "ShipHero production database"
      guide       = "Connect with DATABASE_URL. The readonly plan reaches the replica."
      env         = ["DATABASE_URL"]
      plans = {
        readonly = {
          description  = "The read replica"
          destinations = [{ cidr = "10.20.5.0/24", ports = [5432] }]
        }
        readwrite = {
          description  = "The primary"
          destinations = [{ cidr = "10.20.4.0/24", ports = [5432] }]
        }
      }
    }
  }
}

system name

Meaning
A DNS label of 3 to 63 lowercase letters, digits, and hyphens, not starting with valet-, which Valet's own providers such as valet-postgresql use. Admins see it in the catalog

description

Meaning
Required, not blank. One line the catalog shows

guide

Meaning
Required, not blank. Text shown to the Admin who creates the resource

env

Meaning
Required, at least one name, none repeated. The names of the environment variables the Admin fills, such as DATABASE_URL. The app reads them. A name the agent runtime reserves is refused: VALET_ or LD_ prefixes, and names such as PATH, HOME, USER, TERM, TMPDIR, TZ, and CI

plan name

Meaning
A DNS label, as for a system. A plan is one level of access, such as readonly

plan description

Meaning
Required, not blank

destinations

Meaning
Each is an IPv4 network address in CIDR form and the TCP ports the plan reaches

subnet_ids

Meaning
Optional. Launch an app that holds the plan in these subnets. They must be among workload_subnet_ids, or private_subnet_ids when that is unset

Each system needs at least one plan, and each plan at least one destination. A plan may open at most 50 CIDR and port pairs. Terraform refuses an input that valet-api would refuse at startup.

Run valet-dedicated upgrade <tag> after the apply so api, worker, and inference read the new list.

What the module creates

For each plan, a security group named <name>-ps-<system>-<plan>. It has no ingress and one egress rule for each destination and port. An app launched with the group can reach those addresses and nothing more through it. Apps keep the access they already have.

The module changes nothing in your network. Provide these yourself:

  • A route from the workload subnets to each destination, by peering, Transit Gateway, or VPN.
  • An inbound rule on the destination that admits the plan's security group, or the workload subnets' address range.
  • DNS for the destination, if the app connects by name.

Credentials

The module and the operator never see a credential. An org Admin enters them in Valet when creating the resource. valet resources create prompts for each variable in env without echoing it, so it needs a terminal and refuses without one. An agent cannot create the resource; it can ask for access with the MCP attach_resource tool, which opens a secret request that a person completes in the dashboard.

valet resources catalog
valet resources create shiphero-db:readonly
valet resources attach shiphero-db-readonly --app debugger

An Admin confirms an attach. A Developer who runs it sees a request that an Admin approves within 24 hours. Only an Admin creates, detaches, or destroys these resources.

An app that holds a private system starts cold, since a running task cannot change its security groups.

Change or remove a system

Add a system or plan, or change its destinations, by editing the input and applying the module, then run valet-dedicated upgrade <tag>.

To remove a plan or a system, work in this order:

  1. An org Admin detaches the plan from every app, or destroys the resources that use it. valet resources detach stops and restarts the app without access.
  2. The operator removes the plan from private_systems and applies the module.

Do not reverse the order. Valet refuses to start an app that is still attached to a plan that no longer exists, with the problem private_system.missing. A container that already runs keeps its security group, and AWS refuses to delete a group that a running task uses, so the apply fails until the Admin detaches the app and it restarts.