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).
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.
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
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
EnvironmentSpec.DisplayInfo
User-facing display information about the Environment.
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.
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.
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 or Gloo Mesh 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.
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 or Gloo Mesh mode, as TLS is configured by the user on Gateway or VirtualGateway resources respectively.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
