Rack Configuration

Upon completing the Initial Rack Setup steps, the control plane services, including the web console, should be up and running.

In this final step of rack setup, you will configure the external IP addresses to be used by instances, create a user silo, and set up someone as the silo administrator with or without an identity provider (IdP).

Prerequisites

Before proceeding, confirm that the necessary networking preparations and identity provider setup have been completed.

The steps below require you to make use of the Oxide CLI. Download the appropriate binary from https://github.com/oxidecomputer/oxide.rs/releases.

Login Web Console

Open a session in the default browser of your workstation, log into the Oxide web console as the “recovery” user at https://recovery.sys.$oxideDomainName using the password specified during the initial rack setup process.

If you encounter connection time-out errors with the login page, you can follow the instructions here to troubleshoot the issue. Please also work with Oxide Support to generate a session cookie via password authentication so that you can use it in place of the device token required for some of the troubleshooting steps.

Create Device Token

Follow the instructions in the CLI and SDKs guide to create a device token. This token is linked to the recovery user and should only be used for managing rack setup.

Create a User Silo

The following information is required when creating a silo:

attributevalue

name

Must start with a letter and contain only lower-case letters, numbers, and dashes.

description

discoverable

Whether the silo should be included in silo listing queries (non-discoverable silos are accessible only by direct name or id reference).

identity_mode

There are two options

saml_jit

Users are authenticated with SAML using an external authentication provider.

local_user

The source of truth about users is maintained in the Oxide system.

admin_group_name

Optional. If specified with saml_jit identity mode, this group will be created during silo creation and granted the Silo Admin role.

mapped_fleet_roles

Optional mappings of fleet-level roles conferred by silo roles, applicable to the saml_jit identity_mode only

quotas

Compute and storage resource limits.

cpu

Total number of virtual cpus of all running instances

memory

Total number of bytes of all running instances

storage

Total number of bytes of all disks provisioned

tls_certificates

Initial TLS certificates to be used for the new Silo’s console and API endpoints; should be valid for the Silo’s DNS name which follows the convention $siloName.sys.$oxideDomainName or *.sys.$oxideDomainName for a wildcard certificate.

name

description

cert

key

To create a silo, execute

oxide silo create --json-body silo.json

Here are some examples of the silo.json request payload based on its identity_mode

# identity_mode = saml_jit
# the mapped_fleet_roles enables silo admin group members to act as fleet admin
{
    "name": "$siloName",
    "description": "$siloDescription",
    "discoverable": true,
    "identity_mode": "saml_jit",
    "admin_group_name": "$idpAdminGroup",
    "mapped_fleet_roles": {
      "admin": [
        "admin"
      ]
    },
    "quotas": {
        "cpus": 18,
        "memory": 8589934592,
        "storage": 107374182400
    },
    "tls_certificates": [{
        "name": "initial-install-cert",
        "description": "wildcard certificate",
        "service": "external_api",
        "cert": "$fullCertChainPemBlob",
        "key": "$privateKeyPemBlob"
    }]
}
# identity_mode = local_user
{
    "name": "$siloName",
    "description": "$siloDescription",
    "discoverable": true,
    "identity_mode": "local_only",
    "quotas": {
        "cpus": 18,
        "memory": 8589934592,
        "storage": 107374182400
    },
    "tls_certificates": [{
        "name": "initial-install-cert",
        "description": "wildcard certificate",
        "service": "external_api",
        "cert": "$fullCertChainPemBlob",
        "key": "$privateKeyPemBlob"
    }]
}

Configure Silo Identity Provider

Perform this step only if your silo uses saml_jit for authentication.

The following attributes are required when configuring an identity provider:

attributevalue

name

A short name of the silo’s IdP SAML configuration (the name will be used in the login URL path, see an example under ACL URL).

For ease of tracking, this can be set to the same value as the app or service provider identifier in the IdP but it is not required.

description

Details about the SAML configuration in the identity provider.

idp_metadata_source

Base64 encoded XML of identity provider SAML descriptor; the source can be specified as XML data or a URL for retrieving the metadata. If the URL is used, the rack service must have anonymous access to the endpoint.

type

The valid options are base64_encoded_xml or url.

Use the former option if the provider metadata endpoint is not accessible to the Oxide rack (e.g., due to firewall restrictions); otherwise, use the latter to allow the metadata to be dynamically retrieved from the IdP.

data

Enter the XML exported from the IdP as a single base64-encoded string if type is set to base64_encoded_xml.

url

Enter the IdP endpoint for retrieving the XML if type is set to url.

Examples:
https://keycloak.acme.com/auth/realms/oxide/protocol/saml/descriptor
https://acme.okta.com/app/exkckkgd1nCAfPsUD234/sso/saml/metadata

idp_entity_id

IdP SAML issuer ID or client root URL.

Examples:
https://keycloak.acme.com/auth/realms/oxide
https://accounts.google.com/o/saml2?idpid=D12wdrk34
http://www.okta.com/exkckkgd1nCAfPsUD234

sp_client_id

The IdP ID that uniquely identifies the Oxide client; it may be labeled as service provider, app, or audience.

acs_url

The single sign-on URL, the Oxide Console endpoint registered with the identity provider for responses and assertions.

For example, if the silo name is it-ops, the IdP config name is okta, and the Oxide domain is oxide.acme.com, the login URL will be:

https://it-ops.sys.oxide.acme.com/login/it-ops/saml/okta

slo_url

Single logout endpoint, may be set to the same value as ACS URL (i.e., taking user back to the Oxide Console login page).

technical_contact_email

Email address of identity provider support contact (Note: Oxide rack does not generate email notifications at this time).

signing_keypair

Used by the client for signing the login request; must be in the form of base64-encoded der files.

public_cert

private_key

group_attribute_name

The custom attribute in the SAML access token response that represents the user’s group memberships. The information will be used to create user groups and assign the user to them.

To configure the IdP for the silo created above, execute one of the following commands depending on how you want to specify the IdP metadata

oxide silo idp saml create --silo $siloName --json-body idp.json --metadata-value $base64EncodedMetadataXml

or

oxide silo idp saml create --silo $siloName --json-body idp.json --metadata-url $idpMetadataUrl

Here is a sample request payload of the idp.json file for a silo named "corp" on the delegated domain "oxide.acme.com" with a Google SAML provider.

{
  "name": "google",
  "description": "Corporate silo google SAML provider",
  "idp_entity_id": "https://accounts.google.com/o/saml2?idpid=D12wdrk34",
  "sp_client_id": "corp",
  "idp_metadata_source": {
     "type": "base64_encoded_xml",
     "data": ""
  },
  "acs_url": "https://corp.sys.oxide.acme.com/login/corp/saml/google",
  "slo_url": "https://corp.sys.oxide.acme.com/login/corp/saml/google",
  "technical_contact_email": "infra@acme.com",
  "signing_keypair": {
     "public_cert": "$base64EncodedDer",
     "private_key": "$base64EncodedDer"
  }
  "group_attribute_name": "admins"
}
Note
If the silo or the identity provider is incorrectly configured, you can log into the Recovery Silo to delete the silo and recreate it with the correct configuration.

Create Local Users

Perform this step only if your silo uses local_user for authentication.

To create the first user in the silo and grant this user administrator access, execute

# create user
oxide silo idp local user create --silo $siloName --json-body user.json

# grant silo admin role
oxide silo policy update --silo $siloName --json-body policy.json

# grant fleet admin role
oxide system policy update --json-body policy.json

Here is how the user.json and policy.json payloads should look like

# user.json
{
  "external_id": "$loginname",
  "password": {
    "mode": "password",
    "value": "$passwordValue"
  }
}
# policy.json
{
  "role_assignments": [{
    "identity_id": "$idReturnedFromCreateUser",
    "identity_type": "silo_user",
    "role_name": "admin"
  }]
}

Test User Login

On a separate browser tab or window, log into the newly created silo at https://$siloName.sys.$oxideDomainName, either as yourself via the identity provider or as the local administrator using password authentication.

In the case of IdP integration, if the admin group attributes are configured correctly, your account should be imported into the rack with the silo “admin” role automatically granted. You can confirm your group assignments in the Profile page under Settings.

Important
Before logging in, ensure your account in the IdP is part of the group specified in the admin_group_name of the silo.

Create and configure IP Pool

IP pools are logical abstractions for external IP address allocation. Each silo may have one or more IP pools associated with it and must have one of them set as the default. When a VM instance is provisioned, IP addresses will be automatically assigned from the IP pool specified in the request as long as the pool is linked to the silo.

Follow these steps to create your first IP pool and link it to the new silo:

# create the IP pool
oxide ip-pool create --name $poolName --description $poolDescription

# insert an address range into the new IP pool
oxide ip-pool range add --pool $poolName --first $firstIpInRange --last $lastIpInRange

# link the pool to your new silo and make it the default
oxide ip-pool silo link --pool $poolName --silo $siloName --is-default true

An IP pool may include one or multiple address ranges and they do not need to be contiguous. The number of IP addresses to allocate to each pool will depend on the expected number of VM instances using it. You can always start with a small IP range and add more address ranges later on.

Note
Each VM is assigned a quarter of an external IP address for NAT-ing egress traffic whether it has an ephemeral or floating IP or not. When sizing the IP pool capacity, your estimations will have to include the NAT usage as well.

Additional context and considerations about the data network are available in the Network Preparations and IP Pools guides.

Last updated