An Environment represents information about a set of domains that serve a set of APIProduct versions.
Environments control route creation and route-level configuration (e.g. rate limits, user access).
Field
Type
Label
Description
domains
[]string
repeated
The domains that will serve the APIProducts in this Environment. Domains must be unique across all Environments that have gateway route generation enabled (i.e. that have gatewayConfig.disableRoutes: false). These must be valid FQDN or wildcard hostnames. When using Istio, these domains must match one or more hosts inside the servers field on the Istio Gateway resource.
basePath
string
If set, Gloo Portal will prepend this value to the path of all API Product operations included in this Environment. If route generation is enabled, Gloo Portal will additionally prepend the value to the path matchers of all the generated routes and configure the API gateway to strip the prefix before sending the request to the API backend. The reserved value “{%version%}” will be resolved by Gloo Portal to the identifier of the APIProduct version that an operation belongs to. You should use this feature when two API Product versions include operations that might short-circuit each other. For example, if v1 and v2 of your API Product both expose a GET operation for the /foo resource you can set base_path to “{%version%}” when you include the two version in an Environment; this will cause the path of the operation to be /v1/foo and /v2/foo respectively. Placeholders of the form “{%label:%}” will resolve to the respective label value for the APIProduct version that an operation belongs to. This may be helpful in cases where version is too coarse or insufficient as a differentiator.
This array of selector objects determines which APIProducts are part of this Environment. The set of selected APIProducts is the union of the APIProducts matched by all the selectors. This means an API Product will be selected by the array of selector objects if it matches any of the selectors. If an APIProduct is matched by more than one selector and the relevant selectors have conflicting configuration (e.g. they define different Usage Plans), then the Environment will be rejected. API Products that are not in Succeeded state will be ignored and not added to the Environment
Values for resources (e.g. API Products) that have been parameterized based on their Environment.
preserveApiDocSecurity
bool
This field determines which security schemes are presented to users in the Portal UI for OpenAPI APIs By default security settings from API Docs will be overwritten if any Usage Plans apply If set to true, preserve any security settings from API Docs in addition to any set via Usage Plans
User-facing display information about the Environment.
Field
Type
Label
Description
displayName
string
description
string
EnvironmentSpec.GatewayConfig
Field
Type
Label
Description
disableRoutes
bool
If true, Gloo does not generate gateway routes or virtual service for the API Products published in this environment. You might disable routes so that you can edit the routes and virtual service yourself. Otherwise when enabled, Gloo overwrites any edits..
Custom labels that will be added to the gateway resource (VirtualService for Gloo Edge) that Gloo Portal generates for this Environment. Any labels that use a reserved key name (e.g. environments.portal.gloo.solo.io) will be ignored.
options
gloo.solo.io.VirtualHostOptions
This field can be used to set arbitrary options on the generated VirtualService when running in Gloo Edge mode. A fully documented list of the available options can be found in the Gloo Edge documentation here. It is important to note that the following options are currently not supported: ratelimit_basic, ratelimit, rate_limit_configs, and extauth. If any of these options are used, the Environment will be rejected. We have to impose this constraint as the aforementioned options will result in conflicts with the options that Gloo Portal needs to set to implement its own APIs (e.g. rate limit and auth options are set based on Usage Plans). If basePath is set, the prefix_rewrite and regex_rewrite options will also be rejected, as they would conflict. We will probably relax these constraints in the future, pending a review of the APIs that would cause the conflicts. If cors is set, it will override the default config provided by Gloo Portal. It will be up to the user to make sure CORS is configured correctly to work with the “Try it out” feature in the Developer Portal UI.
httpsRedirect
bool
This field can be used to automatically redirect HTTP traffic to HTTPS for APIs in this Environment. If the value is true and we are running in Gloo Edge mode, Gloo Portal will generate an auxiliary VirtualService to handle HTTPS redirects. tls.enabled needs to be set to true for this configuration to take effect. The field is ignored when running in Istio mode, as TLS is configured by the user on Gateway or VirtualGateway resources respectively.
Definitions for parameterized routes that can appear on resources contained by this Environment. The RouteSpecifier cannot be an environmentRoute. The key represents the unique identifier of the route within this Environment and must follow the DNS label standard as defined in RFC 1123, i.e. it must consist of lower case alphanumeric characters, ‘-’ or ‘.', and must start and end with an alphanumeric character.
Definitions for Usage Plans that can appear on resources contained by this Environment. The key represents the unique identifier of the Usage Plan within this Environment and must follow the DNS label standard as defined in RFC 1123, i.e. it must consist of lower case alphanumeric characters, ‘-’ or ‘.', and must start and end with an alphanumeric character.
Indicates whether the API Products published in this Environment require HTTPS. When set to true, if a user browses the documentation for any API in this environment in a portal, the server URL for that API will contain the https:// scheme; test requests sent via the portal will also use HTTPS.
config
gloo.solo.io.SslConfig
This field is required to correctly configure TLS on the VirtualServices that are generated by Gloo Portal when Gateway route generation is enabled for this Environment and you are running in Gloo Edge mode. The field is ignored when running in Istio mode, as TLS is configured by the user on Gateway or VirtualGateway resources respectively.
EnvironmentStatus
Field
Type
Label
Description
observedGeneration
int64
The observed generation of the Environment. When this matches the Environment's metadata.generation, it indicates the status is up-to-date.
The set of labels that are observed in the metadata.labels on the Environment. We need to keep track of these labels so we can notify resources that depend on the APIProduct via a label selector (i.e. Users and Groups) if they change.
Information about a Portal which references this Environment.
Field
Type
Label
Description
name
string
The name of the Portal.
namespace
string
The namespace of the Portal.
domains
[]string
repeated
A list of the Portal domains which currently give access to APIProducts in this Environment. This is required to properly configure CORS policies for the Environment so that it can be queried from the interactive API documentation published in the Portal.
A list of the API Products which the Portal currently gives access to in this Environment. This is required to properly configure CORS policies for the gateway resources corresponding to the Environment.
ProductSelector
Represents criteria to select APIProducts.
The selection criteria specified by the selector are evaluated as operands in a logical AND expression.
This means the selector will match APIProducts that meet all of its criteria.
Field
Type
Label
Description
names
[]string
repeated
Select only APIProducts whose name matches one of the values specified in this field. If omitted, APIProducts will be selected regardless of name.
namespaces
[]string
repeated
Select only APIProducts which are defined in one of these namespaces. The reserved value * can be used to select APIProducts in all namespaces watched by Gloo Portal. If omitted, we only select APIProducts which are in the same namespace as the Environment.
Select only APIProducts whose labels match all the given logical expressions. If omitted, APIProducts will be selected regardless of labels. The expressions follow the same rules as the RouteTable selector expressions in Gloo Edge (see an example here.
Determines which versions of the matching APIProducts are selected. All the attributes specified in this field are evaluated as operands of a logical AND expression. If omitted, all versions of the matching APIProducts will be selected.
usagePlans
[]string
repeated
A list of Usage Plans available for accessing the APIProducts matched by this selector. Each value must be a valid reference to a Usage Plan parameter defined on the Environment. If none are specified, unlimited access will be enabled for unauthorized users.
basePath
string
If set, Gloo Portal will prepend this value to the path of the operations that belong to the API Products that are matched by this selector. If route generation is enabled, Gloo Portal will additionally prepend the value to the path matchers of all the generated routes and configure the API gateway to strip the prefix before sending the request to the API backend. If base_path is also set at the root of the Environment spec, the its value will be prepended to this one. The reserved value “{%version%}” will be resolved by Gloo Portal to the identifier of the APIProduct version that the operation belongs to. You should use this feature when two API Product versions include operations that might short-circuit each other. For example, if v1 and v2 of your API Product both expose a GET operation for the /foo resource you can set base_path to “{%version%}” when you include the two version in an Environment; this will cause the path of the operation to be /v1/foo and /v2/foo respectively. Placeholders of the form “{%label:%}” will resolve to the respective label value for the APIProduct version that an operation belongs to. This may be helpful in cases where version is too coarse or insufficient as a differentiator.
ProductSelector.VersionSelector
Represents criteria to select APIProduct versions.
All the fields are evaluated as operands of a logical AND expression.
This means the selector will match APIProducts that meet all of its criteria.
Field
Type
Label
Description
tags
[]string
repeated
Select only APIProduct versions that match all the given tags. If omitted, APIProduct versions will be selected regardless of tags.
names
[]string
repeated
Select only APIProducts versions whose name matches one of the values specified in this field. If omitted, APIProducts versions will be selected regardless of name.
SecretKey
Field
Type
Label
Description
name
string
(Required) The key of the secret data entry to inspect.
required
bool
If this field is set to true, Gloo will reject an API key secret that does not contain the given key. Defaults to false. In this case, if a secret does not contain the requested data, no header will be added to the request.
UsagePlan
A UsagePlan describes a policy applied to consumers of an APIProduct.
Consumers will authenticate using OAuth 2.0 access tokens. Only one OAuth Usage Plan may exist for an APIProduct within each Environment. Tokens are obtained using the Authorization Code flow.
Consumers will authenticate using both API Keys created under this Usage Plan and using OAuth 2.0 access tokens. OAuth config for APIKeyPlusOAuth UsagePlans will be derived from the OAuth UsagePlan referenced by name. All APIKeyPlusOAuth plans on a given Product must reference the same OAuth UsagePlan. The referenced OAuth UsagePlan must be specified on the Environment, however no OAuth UsagePlans may be used on a Product with any APIKeyPlusOAuth UsagePlans.
UsagePlan.AuthPolicy.APIKey
UsagePlan.AuthPolicy.APIKeyPlusOAuth
Field
Type
Label
Description
oauthPolicyRef
string
The name of the OAuth usage plan within the Environment to derive OAuth policy from
UsagePlan.AuthPolicy.OAuth
Field
Type
Label
Description
authorizationUrl
string
The URL of the authorization server's authorization endpoint. This value will be displayed as part of the API documentation in portal applications and used to initiate the authorization code flow through which users can request access tokens to test an API.
tokenUrl
string
The URL of the authorization server's token endpoint. This value will be displayed as part of the API documentation in portal applications and used during the authorization code flow through which users can request access tokens to test an API.
The available access token scopes. Portal users will be able to select a set of scopes when requesting an access token.
tokenFieldName
string
By default, when a user requests a token from the OAuth server via the interactive documentation, the portal application will extract the token value from the access_token attribute of the token endpoint response and use it in the Authorization header when a user tests an API. You can use this option to extract the token from a different attribute instead; for example, you could set it to id_token to use the ID token instead of the access token if your OAuth2.0 server also supports OpenID Connect.
introspectionValidation
enterprise.gloo.solo.io.IntrospectionValidation
Configuration for validating access tokens using OAuth Token Introspection RFC7662.
jwtValidation
enterprise.gloo.solo.io.JwtValidation
Configuration for validating access tokens that are JSON Web Token (JWT).
UsagePlan.AuthPolicy.OAuth.Scope
Field
Type
Label
Description
required
bool
If set to true, Gloo Portal will configure the gateway to require that the given scope be present on tokens used to access the API for which this auth policy is defined. The way in which scope information is derived from a token depends on which token validation method is configured. This value is only relevant if gateway route generation is enabled for the Environment on which the auth policy is defined.
description
string
An optional description for this token scope. This value will be displayed as part of the API documentation in portal applications.
