Environment

Proto: environment.proto

Package: portal.gloo.solo.io

Types:

EnvironmentSpec

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.
apiProducts []portal.gloo.solo.io.ProductSelector repeated 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
displayInfo portal.gloo.solo.io.EnvironmentSpec.DisplayInfo User-facing info to display to GUI users for this Environment.
gatewayConfig portal.gloo.solo.io.EnvironmentSpec.GatewayConfig Customization options for generated gateway resources.
parameters portal.gloo.solo.io.EnvironmentSpec.Parameters 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
customHeadersFromApikey []portal.gloo.solo.io.EnvironmentSpec.CustomHeadersFromApikeyEntry repeated Additional headers to be added to HeadersFromMetadata field in the APIKeyAuth

EnvironmentSpec.CustomHeadersFromApikeyEntry

Field Type Label Description
key string
value portal.gloo.solo.io.SecretKey

EnvironmentSpec.DisplayInfo

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..
tls portal.gloo.solo.io.EnvironmentSpec.TlsConfig TLS configuration for the API Products published in this Environment.
virtualServiceLabels []portal.gloo.solo.io.EnvironmentSpec.GatewayConfig.VirtualServiceLabelsEntry repeated 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.

EnvironmentSpec.GatewayConfig.VirtualServiceLabelsEntry

Field Type Label Description
key string
value string

EnvironmentSpec.Parameters

Field Type Label Description
routes []portal.gloo.solo.io.EnvironmentSpec.Parameters.RoutesEntry repeated 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.
usagePlans []portal.gloo.solo.io.EnvironmentSpec.Parameters.UsagePlansEntry repeated 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.

EnvironmentSpec.Parameters.RoutesEntry

Field Type Label Description
key string
value portal.gloo.solo.io.RouteSpecifier

EnvironmentSpec.Parameters.UsagePlansEntry

Field Type Label Description
key string
value portal.gloo.solo.io.UsagePlan

EnvironmentSpec.TlsConfig

Field Type Label Description
enabled bool 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.
state common.portal.gloo.solo.io.State The current state of the Environment.
reason string A human-readable string explaining the error, if any.
modifiedDate google.protobuf.Timestamp Most recent date the Environment was updated.
observedLabels []portal.gloo.solo.io.EnvironmentStatus.ObservedLabelsEntry repeated 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.
publishedPortals []portal.gloo.solo.io.EnvironmentStatus.ReferencingPortal repeated The set of Portals on which APIProducts included in this Environment are published. Includes routing data about the Portals relevant to the Product.
apiProducts []portal.gloo.solo.io.EnvironmentStatus.APIProductDetails repeated All APIProducts referenced by this Environment, along with any additional info about them that's needed.

EnvironmentStatus.APIProductDetails

Field Type Label Description
name string The name of the target APIProduct.
namespace string The namespace of the target APIProduct.
versions []portal.gloo.solo.io.EnvironmentStatus.APIProductDetails.VersionsEntry repeated The names of the Versions of this API Product, mapped to any info about them that's needed.
usagePlans []string repeated A list of Usage Plans available for accessing the APIProduct in this Environment.
basePath string This field is deprecated and no longer set by the controller

EnvironmentStatus.APIProductDetails.VersionsEntry

Field Type Label Description
key string
value portal.gloo.solo.io.EnvironmentStatus.APIProductVersionDetails

EnvironmentStatus.APIProductVersionDetails

Field Type Label Description
routes []portal.gloo.solo.io.APIRoute repeated The routes associated with this API Product Version.
apiType portal.gloo.solo.io.APIType The kind of API this version has (e.g. OpenAPI, gRPC)
basePath string Resolved base path for this API Product Version
customRouteTable common.portal.gloo.solo.io.ObjectRef The reference to this Version's CustomRouteTable

EnvironmentStatus.ObservedLabelsEntry

Field Type Label Description
key string
value string

EnvironmentStatus.ReferencingPortal

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.
apiProducts []common.portal.gloo.solo.io.ObjectRef repeated 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.
labels []common.portal.gloo.solo.io.LabelExpression repeated 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.
versions portal.gloo.solo.io.ProductSelector.VersionSelector 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.

Field Type Label Description
displayName string User-facing display name for the plan.
rateLimit portal.gloo.solo.io.UsagePlan.RateLimitPolicy The rate limits enforced for users (API Consumers) of the plan. Leave empty to allow unlimited API access for users of this plan.
authPolicy portal.gloo.solo.io.UsagePlan.AuthPolicy The auth policy for this plan.
customAuthConfig core.solo.io.ResourceRef Config from the specified auth config will be appended to config generated by Portal for the UsagePlan's AuthPolicy

UsagePlan.AuthPolicy

Field Type Label Description
unauthorized portal.gloo.solo.io.UsagePlan.AuthPolicy.Unauthorized Consumers do not require authorization to use this plan. If there is any Unauthorized Usage Plan on an API Product it must be the only Usage Plan
apiKey portal.gloo.solo.io.UsagePlan.AuthPolicy.APIKey Consumers will authenticate using API Keys created under this Usage Plan.
oauth portal.gloo.solo.io.UsagePlan.AuthPolicy.OAuth 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.
apiKeyPlusOauth portal.gloo.solo.io.UsagePlan.AuthPolicy.APIKeyPlusOAuth 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.
scopes []portal.gloo.solo.io.UsagePlan.AuthPolicy.OAuth.ScopesEntry repeated 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.

UsagePlan.AuthPolicy.OAuth.ScopesEntry

Field Type Label Description
key string
value portal.gloo.solo.io.UsagePlan.AuthPolicy.OAuth.Scope

UsagePlan.AuthPolicy.Unauthorized

Field Type Label Description
global portal.gloo.solo.io.UsagePlan.AuthPolicy.Unauthorized.Global Global applies a single limit to all traffic for the product

UsagePlan.AuthPolicy.Unauthorized.Global

UsagePlan.RateLimitPolicy

A Rate Limit policy that can be applied to request traffic from an authorized client.

Field Type Label Description
unit portal.gloo.solo.io.UsagePlan.RateLimitPolicy.Unit
requestsPerUnit uint32

UsagePlan.RateLimitPolicy.Unit

Name Number Description
UNKNOWN 0
SECOND 1
MINUTE 2
HOUR 3
DAY 4