Environment Variables

Environment variables are how configuration flows into your services. Lucity supports four types: shared variables, service variables, database references, and service references.

Shared variables

Shared variables apply to all services in an environment. Use them for configuration that's common across your stack: API URLs, feature flags, log levels.

mutation {
  setSharedVariables(
    projectId: "myapp"
    environment: "production"
    variables: [
      { key: "LOG_LEVEL", value: "info" }
      { key: "API_BASE_URL", value: "https://api.example.com" }
    ]
  )
}

Query them back:

query {
  sharedVariables(projectId: "myapp", environment: "production") {
    key
    value
  }
}

Shared variables are stored in the GitOps repo as Helm values and deployed as ConfigMaps. Every service in the environment receives them.

Service variables

Service variables are scoped to a single service. They override shared variables when both define the same key.

mutation {
  setServiceVariables(
    projectId: "myapp"
    environment: "production"
    service: "api"
    variables: [
      { key: "PORT", value: "3000" }
      { key: "LOG_LEVEL", value: "debug" }
    ]
  )
}

In this example, the api service gets LOG_LEVEL=debug while all other services get LOG_LEVEL=info from the shared variable.

Database references

Instead of copying database connection strings manually, reference a database and Lucity injects the credentials automatically.

mutation {
  setServiceVariables(
    projectId: "myapp"
    environment: "production"
    service: "api"
    variables: [
      {
        key: "DATABASE_URL"
        databaseRef: { database: "main", key: "uri" }
      }
    ]
  )
}

Available database reference keys:

Database references pull values from the Kubernetes Secret that CloudNativePG generates automatically. When credentials rotate, your services pick up the new values on the next restart.

Service references

Connect services to each other by generating internal URLs automatically.

mutation {
  setServiceVariables(
    projectId: "myapp"
    environment: "production"
    service: "frontend"
    variables: [
      {
        key: "API_URL"
        serviceRef: { service: "api" }
      }
    ]
  )
}

This injects the internal Kubernetes DNS address of the referenced service, so your frontend can reach the API without hardcoding hostnames. The reference resolves to a service-name.namespace.svc.cluster.local address, which works inside the cluster and survives ejection.

How variables map to Kubernetes

All variable configuration lives in the GitOps repo as Helm values. After ejection, variables continue working as standard Kubernetes ConfigMaps, Secrets, and pod environment variables.