environment.proto

Package : portal.gloo.solo.io

Top

environment.proto

Table of Contents

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. 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.
apiProducts []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.
displayInfo EnvironmentSpec.DisplayInfo User-facing info to display to GUI users for this Environment.
gatewayConfig EnvironmentSpec.GatewayConfig Customization options for generated gateway resources.
parameters EnvironmentSpec.Parameters Values for resources (e.g. API Products) that have been parameterized based on their Environment.

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, do not generate gateway routes for the API Products published in this environment.
tls EnvironmentSpec.TlsConfig TLS configuration for the API Products published in this Environment.
virtualServiceLabels []EnvironmentSpec.GatewayConfig.VirtualServiceLabelsEntry repeated Custom labels that will be added to the VirtualService 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: cors, 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.

EnvironmentSpec.GatewayConfig.VirtualServiceLabelsEntry

Field Type Label Description
key string
value string

EnvironmentSpec.Parameters

Field Type Label Description
routes []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 []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 RouteSpecifier

EnvironmentSpec.Parameters.UsagePlansEntry

Field Type Label Description
key string
value 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 resources.

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 []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 []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 []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 []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 The base path for this APIProduct. This value accounts for any base_path set at the root of the Environment spec.

EnvironmentStatus.APIProductDetails.VersionsEntry

Field Type Label Description
key string
value EnvironmentStatus.APIProductVersionDetails

EnvironmentStatus.APIProductVersionDetails

Field Type Label Description
routes []APIRoute repeated The routes associated with this API Product Version.
apiType APIType The kind of API this version has (e.g. OpenAPI, gRPC)

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 virtual service 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 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.

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.

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 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 UsagePlan.AuthPolicy The auth policy for this plan.

UsagePlan.AuthPolicy

Field Type Label Description
unauthorized UsagePlan.AuthPolicy.Unauthorized Consumers do not require authorization to use this plan. Only one Unauthorized Usage Plan may exist for an APIProduct.
apiKey UsagePlan.AuthPolicy.APIKey Consumers will authenticate using API Keys created under this Usage Plan.
oauth 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.

UsagePlan.AuthPolicy.APIKey

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 []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.AccessTokenValidation.IntrospectionValidation Configuration for validating access tokens using OAuth Token Introspection RFC7662.
jwtValidation enterprise.gloo.solo.io.AccessTokenValidation.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 UsagePlan.AuthPolicy.OAuth.Scope

UsagePlan.AuthPolicy.Unauthorized

UsagePlan.RateLimitPolicy

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

Field Type Label Description
unit UsagePlan.RateLimitPolicy.Unit
requestsPerUnit uint32

UsagePlan.RateLimitPolicy.Unit

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