Environments¶

Overview¶

The Environments feature in Yappes lets you create and manage gateway environments — named environments with one or more domains used for gateway routing, API promotion, and related Gateway Control workflows.

With this feature, you can:

Create gateway environments with custom domain mappings.
Designate one environment as the default environment.
View, edit, and delete environments from a single list.
Search environments by name.

Gateway environments are also referenced when creating Applications, configuring KVM Store entries, and promoting APIs via Promote Environment.

Why This Matters¶

Separate gateway domains for the same API across different deployment contexts.
A single default environment for baseline gateway routing.
Controlled domain assignment with uniqueness checks across environments.
Foundation for promoting APIs into additional gateway environments.

Scope¶

Gateway environment creation, viewing, editing, and deletion.
Domain management per environment.
Dataplane assignment from unattached dataplanes.
Default environment designation and change confirmation.
Environment list search and management.

Outcome¶

Organized gateway environments ready for API promotion and other Gateway Control features.
Clear domain ownership per environment.
Predictable default-environment behavior for new API's.

Prerequisites¶

Required Access and Permissions¶

Users must have:

API Manager access.
Permission to manage gateway environments.

System / Technical Requirements¶

Valid organization context in the API Manager.
Domain hostnames ready for assignment (no protocol prefixes or path segments).
At least one unattached dataplane available to assign. Register dataplanes in Yappes Fleet — Dataplane if none appear in the selector.

Features¶

Environment list — list all gateway environments with domain counts and created timestamps.
Search — filter environments by name.
Create Environment — add a new environment with domains, a dataplane, and optional default flag.
View / Edit — inspect environment details or update name, description, domains, dataplane, and default status.
Delete — remove environments that are not default and not attached to an API.
Default environment — one environment can be marked default; the default row is visually highlighted in the list.

Environment Fields¶

Field	Required	Description
Environment name	Yes	Display name for the environment. Must start with a letter and be at least 3 characters.
Description	No	Optional notes about the environment. Maximum 500 characters.
Domains	Yes (at least one)	Hostnames served by this environment (for example, `api.example.com`).
Dataplane	Yes	Select a dataplane that is not already attached to another environment. Placeholder: `Select here`. On edit, the currently assigned dataplane remains available.
Make Default Environment	No	When enabled, this environment becomes the platform default. Only one default is allowed at a time.

Domain Validation Rules¶

Rule	Detail
Format	Valid hostname only — no `http://` or `https://`, no path segments, no wildcard subdomains (`*.`)
Whitespace	Domains must not contain spaces
Uniqueness (within form)	Duplicate domains in the same environment are not allowed
Uniqueness (across environments)	A domain cannot already be assigned to a different environment
Minimum rows	At least one domain row is required; the last row cannot be removed if it is the only one

Step-by-Step Implementation¶

Creating an Environment¶

Step 1: Navigate to Environments¶

From the left navigation panel, open Gateway Control → Environments.

Step 2: Open the Create Form¶

Click Create Environment.

Step 3: Enter Environment Details¶

Configure the form:

Field	Action
Environment name	Enter a valid name
Description	Optionally add a description
Domains	Enter at least one domain (placeholder: `e.g. test-1.xyz.com`)
Dataplane	Select an unattached dataplane (placeholder: `Select here`)
Make Default Environment	Optionally enable to set as default

No unattached dataplanes

If no dataplanes are available to attach, the form shows: "There are no data planes available to attach to this environment. Please ask your administrator to create one." Create Environment stays disabled until an administrator registers an unattached dataplane.

Step 4: Manage Domain Rows¶

Click Add Domain to add another domain row. This button is disabled until all existing domain rows are valid and non-empty.
Use the remove control on a domain row to delete it. Removal is disabled when only one domain row remains.

Step 5: Confirm Default Change (if applicable)¶

If you enable Make Default Environment and another default already exists, a Change default environment confirmation appears. Review the message and confirm to proceed.

Changing the default environment

Only one environment can be the default at a time. Confirming assigns default status to the new environment and removes it from the current default. The previous default environment remains available in the list but is no longer marked as default.

Step 6: Save¶

Click Create Environment.

Success

The environment is successfully created and appears in the environments list.

Viewing and Editing an Environment¶

Step 1: Open View Mode¶

In the environments list, click View (eye icon) on the target row.

Step 2: Review Details¶

The View Environment dialog shows all fields in read-only mode.

Step 3: Switch to Edit Mode¶

Click Edit to open Update Environment.

Step 4: Apply Changes¶

Update allowed fields and click Update Environment.

Success

The environment is successfully updated and the list refreshes with your changes.

Edit constraints:

Condition	Behavior
Environment is the default	`Make Default Environment` is locked on with the message: "This is the default environment, so this cannot be turned off here."
Environment is attached to an API	The first domain row is read-only. Helper text: "The first domain cannot be changed or removed while this environment is attached to an API."
Environment is the default	The first domain row is read-only. Helper text: "The first domain cannot be changed or removed on the default environment."
No fields changed	Error: "Please modify values to initiate an update."

Deleting an Environment¶

Step 1: Open Delete Confirmation¶

In the environments list, click Delete (trash icon) on the target row.

Step 2: Review Summary¶

The Delete Environment dialog shows:

Environment name
No.of.Domains
Created Date
Dataplane

Step 3: Confirm or Cancel¶

Click Delete to remove the environment, or Cancel to close without changes.

Delete constraints (blocked before the API call):

Condition	Message
Environment is the default	"You cannot delete the default environment. Choose another environment as default, then delete this one."
Environment is attached to an API	"You cannot delete the environment that is attached to an API."

To delete a former default environment, first assign another environment as default, then delete the old one.

Best Practices¶

Practice	Reason
Register dataplanes before creating environments	Each environment requires an unattached dataplane
Plan domains before creation	Domains must be unique across all environments
Keep one clear default environment	Simplifies promotion and platform defaults
Use descriptive environment names	Easier search and audit in the list
Detach or reassign APIs before deleting	Environments attached to APIs cannot be deleted
Change default before deleting the old default	Default environments cannot be deleted directly

Troubleshooting¶

Issue	Possible Cause	Resolution
Duplicate domain error	Same domain entered twice in the form	Remove or change the duplicate domain
Domain already in use	Domain assigned to another environment	Choose a different hostname or edit the other environment
No dataplanes in the selector	All dataplanes are already attached, or none are registered	Ask an administrator to register an unattached dataplane in Yappes Fleet — Dataplane
Unable to load dataplanes	Dataplane list request failed	Retry opening the form; confirm Admin Console / fleet connectivity
Create Environment disabled	No unattached dataplane available	Register an unattached dataplane, then reopen `Create Environment`
Cannot delete environment	Environment is default or attached to an API	Assign a new default and/or detach APIs first
Cannot change first domain	Environment is default or attached to an API	Add or edit additional domain rows instead
Add Domain disabled	Existing domain rows are empty or invalid	Complete validation on all current rows
Update rejected with no changes	Form values match the saved record	Change at least one field before saving
Default switch locked on edit	Editing the current default environment	Assign another environment as default first if you need to remove default status

Frequently Asked Questions¶

What is a gateway environment?

A gateway environment is a named set of domains used by the API gateway for routing and promotion. It is separate from backend service URLs configured during API onboarding.

How many default environments can exist?

Only one environment can be the default at a time. Changing the default requires confirmation when another default already exists.

Can I use the same domain in two environments?

No. Each domain must be unique across all gateway environments.

Tip

Create and validate gateway environments before promoting APIs. Promotion requires at least one environment and a target environment that is not already attached to the API.