Navigation :

Install Portal

As a Gloo Platform administrator, you must enable the Portal add-on as part of the Gloo Platform installation. Many of the administrator's tasks are one-time configuration decisions, and then maintaining the feature with periodic upgrades or monitoring activities.

Portal is a Gloo Platform module that is included with a Gloo Gateway license. As a platform administrator, you can install, upgrade, and uninstall Portal as you do with other Gloo Platform components.

The instructions on this page install the components for a basic developer portal. You can optionally install additional components such as an OTel gateway and collector agent, Clickhouse logging storage, and Istio access logs, to gather API usage analytics for your developer portal. For setup instructions, see Monitor Portal analytics.

Gloo Mesh Gateway version 2.5.2 has a known issue in Portal that causes interruption during translation. This issue is resolved in version 2.5.3. Portal users are advised to skip version 2.5.2, and to directly upgrade to 2.5.3 instead.

Gloo components for Portal

When you install Gloo Platform, you can choose to set up add-ons that extend the functionality of your environment. To use Portal, you must install several add-ons and other components as follows. In multicluster setups, you install these components in each workload cluster.

External auth server: The external auth server forces your end-users to authenticate before accessing your developer portal, such as via an OpenID Connect (OIDC) provider. Further, you can apply granular API key extauth policies to each API that you want to expose. These policies are part of your portal's usage plan.
Ingress gateway: To expose your APIs externally, the Portal server must be in the same workspace as your ingress gateway.
Rate limiter server: With the rate limiter, you can set up complex usage plans to restrict the number of times that users can access an API. This way, you can offer multiple tiers with more capabilities, as well as prevent your APIs from throttling.
Redis backing database: By default, the portal, external auth, and rate limiting servers share a Redis backing database. When a user logs into the developer portal and issues a request to generate an API key, the portal server writes the API key to the Redis instance. In the portal frontend app, this API key is shown to the user. In subsequent requests to your APIs, the user includes the API key as a header. The Gloo external auth server reads the API key from the same Redis database to ensure the keys match. Then, the user request is authenticated and allowed to proceed. To bring your own Redis database, see Backing databases.
Portal server: The portal server enables you to create multiple Portal custom resources for each developer portal that you want to expose. The server also serves the Developer Portal API that lets your end-users self-service, such as to generate API keys to access the APIs that are included in their usage plans.

You can set up the required Portal components as part of an initial Gloo Platform installation or by upgrading an existing installation.

Set up Portal during Gloo Platform installation

Set up the required Portal components as part of your initial Gloo Platform installation.

Save your cluster name and your Gloo Gateway license key in environment variables. Note: The cluster name must be alphanumeric with no special characters except a hyphen (-), lowercase, and begin with a letter (not a number). If you do not have a license key, contact an account representative.
```
export CLUSTER_NAME=<cluster_name>
export GLOO_GATEWAY_LICENSE_KEY=<license_key>
```

Install Gloo Gateway with the required add-ons, including the external auth, rate limiting, and portal servers.

meshctl - Kubernetes
meshctl - OpenShift
Helm - Kubernetes
Helm - OpenShift

For demo or getting started setups, you can use the basic profiles included in the meshctl install command.

Install the latest version of meshctl.

curl -sL https://run.solo.io/meshctl/install | GLOO_MESH_VERSION=v2.5.5 sh -
export PATH=$HOME/.gloo-mesh/bin:$PATH

Install Gloo Gateway in your cluster. This command uses basic profiles to install the management plane components, such as the management server and Prometheus server, and the data plane components, such as the agent, gateway proxy, rate limit server, external auth server, and portal server, in your cluster. The portal profile also sets up the local Redis instance to be used for backing storage for the servers. For more backing storage options, see Portal server.
```
meshctl install --profiles gloo-gateway-single,portal \
  --set common.cluster=$CLUSTER_NAME \
  --set demo.manageAddonNamespace=true \
  --set glooMgmtServer.createGlobalWorkspace=true \
  --set licensing.glooGatewayLicenseKey=$GLOO_GATEWAY_LICENSE_KEY
```

For demo or getting started setups, you can use the basic profiles included in the meshctl install command.

Install the latest version of meshctl.

curl -sL https://run.solo.io/meshctl/install | GLOO_MESH_VERSION=v2.5.5 sh -
export PATH=$HOME/.gloo-mesh/bin:$PATH

Elevate the permissions of the following service accounts that will be created. These permissions allow the ingress gateway proxy to make use of a user ID that is normally restricted by OpenShift. For more information, see the Istio on OpenShift documentation.

oc adm policy add-scc-to-group anyuid system:serviceaccounts:istio-system
oc adm policy add-scc-to-group anyuid system:serviceaccounts:gloo-mesh-gateways
oc adm policy add-scc-to-group anyuid system:serviceaccounts:gloo-mesh-addons
oc adm policy add-scc-to-group anyuid system:serviceaccounts:gm-iop-1-20

Create the gloo-mesh-gateways and gloo-mesh-addons projects, and create NetworkAttachmentDefinition custom resources for the projects.

kubectl create ns gloo-mesh-gateways kubectl create ns gloo-mesh-addons

cat <<EOF | oc -n gloo-mesh-gateways create -f - apiVersion: "k8s.cni.cncf.io/v1" kind: NetworkAttachmentDefinition metadata: name: istio-cni EOF

cat <<EOF | oc -n gloo-mesh-addons create -f -
apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
  name: istio-cni
EOF

Install Gloo Gateway in your cluster. This command uses basic profiles to install the management plane components, such as the management server and Prometheus server, and the data plane components, such as the agent, gateway proxy, rate limit server, external auth server, and portal server, in your cluster. The portal profile also sets up the local Redis instance to be used for backing storage for the servers. For more backing storage options, see Portal server.
```
meshctl install --profiles gloo-gateway-single-openshift,portal-openshift \
  --set common.cluster=$CLUSTER_NAME \
  --set glooMgmtServer.createGlobalWorkspace=true \
  --set licensing.glooGatewayLicenseKey=$GLOO_GATEWAY_LICENSE_KEY
```

Note: In OpenShift 4.11 and later, you might see warnings for the pods and containers which violate the OpenShift PodSecurity "restricted:v1.24" profile, due to the elevated permissions required by Istio. You can ignore these warnings. For more info, see this article.

Customize your setup by using a Helm values file to install Gloo Gateway and Portal.

Skip the optional add-on installation step, but otherwise follow the Install guide to install Gloo Gateway at version 2.3.0 or later.

Save the following settings for the required add-ons, including the external auth, rate limiting, and portal servers, in a Helm values file. The following example also sets up the local Redis instance to be used for backing storage for the servers. For more backing storage options such as to bring your own Redis with auth, see Portal server.

cat >addons.yaml <<EOF
extAuthService:
  enabled: true
  extAuth:
    apiKeyStorage:
      # Use the local gloo-mesh-addons Redis for backing storage
      name: redis
      enabled: true
      config:
        host: "redis.gloo-mesh-addons:6379"
        # Set to 0 to match the default database for the 'glooPortalServer.apiKeyStorage' configuration
        db: 0
      # Replace with a random string to use to generate hash values for other keys
      secretKey: "ThisIsSecret"
glooPortalServer:
  enabled: true
  apiKeyStorage:
    # Use the local gloo-mesh-addons Redis for backing storage
    redis:
      enabled: true
      address: redis.gloo-mesh-addons:6379
    # Path for API key storage config file in the gloo-mesh-addons backing Redis
    configPath: /etc/redis-client-config/config.yaml
    # Replace with a random string to use to generate hash values for other keys
    secretKey: "ThisIsSecret"
rateLimiter:
  enabled: true
EOF

Install the add-ons in a separate gloo-agent-addons Helm release by using the Helm values file.

helm install gloo-agent-addons gloo-platform/gloo-platform \
   --namespace gloo-mesh-addons \
   --set common.addonsNamespace=gloo-mesh-addons \
   --create-namespace \
   --values addons.yaml \
   --version $GLOO_VERSION \
   --set common.cluster=$CLUSTER_NAME

Customize your setup by using a Helm values file to install Gloo Gateway and Portal.

Skip the optional add-on installation step, but otherwise follow the Install guide to install Gloo Gateway at version 2.3.4 or later.
Elevate the permissions of the gloo-mesh-addons service account that will be created.
```
oc adm policy add-scc-to-group anyuid system:serviceaccounts:gloo-mesh-addons
```

Create the gloo-mesh-addons project, and create a NetworkAttachmentDefinition custom resource for the project.

kubectl create ns gloo-mesh-addons
cat <<EOF | oc -n gloo-mesh-addons create -f -
apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
  name: istio-cni
EOF

cat >addons.yaml <<EOF
extAuthService:
  enabled: true
  extAuth:
    apiKeyStorage:
      # Use the local gloo-mesh-addons Redis for backing storage
      name: redis
      enabled: true
      config:
        host: "redis.gloo-mesh-addons:6379"
        # Set to 0 to match the default database for the 'glooPortalServer.apiKeyStorage' configuration
        db: 0
      # Replace with a random string to use to generate hash values for other keys
      secretKey: "ThisIsSecret"
glooPortalServer:
  enabled: true
  apiKeyStorage:
    # Use the local gloo-mesh-addons Redis for backing storage
    redis:
      enabled: true
      address: redis.gloo-mesh-addons:6379
    # Path for API key storage config file in the gloo-mesh-addons backing Redis
    configPath: /etc/redis-client-config/config.yaml
    # Replace with a random string to use to generate hash values for other keys
    secretKey: "ThisIsSecret"
rateLimiter:
  enabled: true
EOF

Install the add-ons in a separate gloo-agent-addons Helm release by using the Helm values file.

helm install gloo-agent-addons gloo-platform/gloo-platform \
   --namespace gloo-mesh-addons \
   --set common.addonsNamespace=gloo-mesh-addons \
   --values addons.yaml \
   --version $GLOO_VERSION \
   --set common.cluster=$CLUSTER_NAME

Verify that Portal and the related components are installed.

meshctl check

In the example output, make sure that the portal, external auth, and rate limiting servers and all of the core Gloo Gateway components are healthy.

🟢 Gloo Platform License Status
   
 INFO  gloo-gateway enterprise license expires on 05 Nov 23 14:18 EST
   
🟢 CRD Version check
   
🟢 Gloo deployment status
   
Namespace        | Name                           | Ready | Status 
gloo-mesh        | gloo-mesh-agent                | 1/1   | Healthy
gloo-mesh        | gloo-mesh-mgmt-server          | 1/1   | Healthy
gloo-mesh        | gloo-mesh-redis                | 1/1   | Healthy
gloo-mesh        | gloo-mesh-ui                   | 1/1   | Healthy
gloo-mesh        | prometheus-server              | 1/1   | Healthy
gloo-mesh-addons | ext-auth-service               | 1/1   | Healthy
gloo-mesh-addons | gloo-mesh-portal-server        | 1/1   | Healthy
gloo-mesh-addons | rate-limiter                   | 1/1   | Healthy
gloo-mesh-addons | redis                          | 1/1   | Healthy
gloo-mesh        | gloo-telemetry-collector-agent | 3/3   | Healthy

🟢 Mgmt server connectivity to workload agents

Cluster  | Registered | Connected Pod                                   
cluster1 | true       | gloo-mesh/gloo-mesh-mgmt-server-65bd557b95-v8qq6

Verify that the gateway proxy service is created and assigned an external IP address. It might take a few minutes for the load balancer to deploy.

kubectl get svc -n gloo-mesh-gateways

Example output:

NAME                   TYPE           CLUSTER-IP      EXTERNAL-IP      PORT(S)                                                      AGE
istio-ingressgateway   LoadBalancer   10.XX.XXX.XXX   35.XXX.XXX.XXX   15021:30826/TCP,80:31257/TCP,443:30673/TCP,15443:30789/TCP   48s

Set up Portal by upgrading Gloo Platform

Set up the required Portal components by upgrading your existing Gloo Platform installation.

The following steps upgrade an existing Helm release to make sure that the required external auth, rate limiting, and portal servers are set up. The steps do not upgrade the Gloo Platform management server or agent versions or otherwise change the components.

Upgrade your existing installation with the required add-ons.

Helm command
Helm values file

Upgrade your setup by using Helm --set flags.

Check the Helm releases in your cluster. Depending on your installation method, you either have only a main installation release (such as gloo-platform), or a main installation and a separate add-ons release (such as gloo-agent-addons), in addition to your CRDs release.
```
helm ls -A
```

Upgrade your Helm release with the required add-ons. The following examples also set up the local Redis instance to be used for backing storage for the servers. For more backing storage options, see Portal server.

If you have only one release for your installation, upgrade the gloo-platform release. If you migrated from the legacy Helm charts, your Helm release might be named gloo-mgmt or gloo-mesh-enterprise instead. Note: In the following Helm upgrade command, make sure to include the same Helm values that you specifed when you installed Gloo Gateway, either as a configuration file or with --set flags. Otherwise, any previous custom values that you set might be overwritten, which might mean that your Gloo agent and gateway proxies are removed.

helm upgrade gloo-platform gloo-platform/gloo-platform \
   --namespace gloo-mesh \
   -f gloo-gateway-single.yaml \
   --set common.cluster=$CLUSTER_NAME \
   --version $GLOO_VERSION \
   --set extAuthService.enabled=true \
   --set rateLimiter.enabled=true \
   --set glooPortalServer.enabled=true \
   --set glooPortalServer.apiKeyStorage.redis.enabled=true \
   --set glooPortalServer.apiKeyStorage.secretKey="ThisIsSecret" \
   --set glooPortalServer.apiKeyStorage.configPath="/etc/redis-client-config/config.yaml" \
   --set glooPortalServer.apiKeyStorage.redis.address="redis.gloo-mesh-addons:6379" \
   --set extAuthService.extAuth.apiKeyStorage.name=redis \
   --set extAuthService.extAuth.apiKeyStorage.enabled=true \
   --set extAuthService.extAuth.apiKeyStorage.config.host="redis.gloo-mesh-addons:6379" \
   --set extAuthService.extAuth.apiKeyStorage.config.db=0 \
   --set extAuthService.extAuth.apiKeyStorage.secretKey="ThisIsSecret" \
   --version $GLOO_VERSION

If you have a separate add-ons release, upgrade the gloo-agent-addons release. If you previously customized any of the add-ons, make sure to include the same Helm values that you specifed for the add-ons, either as a configuration file or with --set flags.

helm upgrade gloo-agent-addons gloo-platform/gloo-platform \
   --namespace gloo-mesh-addons \
   --set common.cluster=$CLUSTER_NAME \
   --version $GLOO_VERSION \
   --set extAuthService.enabled=true \
   --set rateLimiter.enabled=true \
   --set glooPortalServer.enabled=true \
   --set glooPortalServer.apiKeyStorage.redis.enabled=true \
   --set glooPortalServer.apiKeyStorage.secretKey="ThisIsSecret" \
   --set glooPortalServer.apiKeyStorage.configPath="/etc/redis-client-config/config.yaml" \
   --set glooPortalServer.apiKeyStorage.redis.address="redis.gloo-mesh-addons:6379" \
   --set extAuthService.extAuth.apiKeyStorage.name=redis \
   --set extAuthService.extAuth.apiKeyStorage.enabled=true \
   --set extAuthService.extAuth.apiKeyStorage.config.host="redis.gloo-mesh-addons:6379" \
   --set extAuthService.extAuth.apiKeyStorage.config.db=0 \
   --set extAuthService.extAuth.apiKeyStorage.secretKey="ThisIsSecret" \
   --version $GLOO_VERSION

Upgrade your setup by using a Helm values file.

Check the Helm releases in your cluster. Depending on your installation method, you either have only a main installation release (such as gloo-platform), or a main installation and a separate add-ons release (such as gloo-agent-addons), in addition to your CRDs release.
```
helm ls -A
```
Get your current installation values.
- If you have only one release for your installation, get those values. Note that if you migrated from the legacy Helm charts, your Helm release might be named gloo-mgmt or gloo-mesh-enterprise instead.
```
helm get values gloo-platform -n gloo-mesh -o yaml > gloo-gateway-single.yaml
open gloo-gateway-single.yaml
```
- If you have a separate add-ons release, get those values.
```
helm get values gloo-agent-addons -n gloo-mesh-addons -o yaml > gloo-agent-addons.yaml
open gloo-agent-addons.yaml
```

Add or edit the following settings for the required add-ons, including the external auth, rate limiting, and portal servers. The following example also sets up the local Redis instance to be used for backing storage for the servers. For more backing storage options, see Portal backing databases.

extAuthService:
  enabled: true
  extAuth:
    apiKeyStorage:
      # Use the local gloo-mesh-addons Redis for backing storage
      name: redis
      enabled: true
      config:
        host: "redis.gloo-mesh-addons:6379"
        # Set to 0 to match the default database for the 'glooPortalServer.apiKeyStorage' configuration
        db: 0
      # Replace with a random string to use to generate hash values for other keys
      secretKey: "ThisIsSecret"
glooPortalServer:
  enabled: true
  apiKeyStorage:
    # Use the local gloo-mesh-addons Redis for backing storage
    redis:
      enabled: true
      address: redis.gloo-mesh-addons:6379
    # Path for API key storage config file in the gloo-mesh-addons backing Redis
    configPath: /etc/redis-client-config/config.yaml
    # Replace with a random string to use to generate hash values for other keys
    secretKey: "ThisIsSecret"
rateLimiter:
  enabled: true

Upgrade your Helm release with the required add-ons. The following examples also set up the local Redis instance to be used for backing storage for the servers. For more backing storage options, see Portal server.
- If you have only one release for your installation, upgrade the gloo-platform release. Note that if you migrated from the legacy Helm charts, your Helm release might be named gloo-mgmt or gloo-mesh-enterprise instead.
```
helm upgrade gloo-platform gloo-platform/gloo-platform \
   --namespace gloo-mesh \
   -f gloo-gateway-single.yaml \
   --version $GLOO_VERSION
```
- If you have a separate add-ons release, upgrade the gloo-agent-addons release.
```
helm upgrade gloo-agent-addons gloo-platform/gloo-platform \
   --namespace gloo-mesh-addons \
   -f gloo-agent-addons.yaml \
   --version $GLOO_VERSION
```

Verify that Portal and the related components are installed.

meshctl check

In the example output, make sure that the portal, external auth, and rate limiting servers and all of the core Gloo Gateway components are healthy.

🟢 Gloo Platform License Status
   
 INFO  gloo-gateway enterprise license expires on 05 Nov 23 14:18 EST
   
🟢 CRD Version check
   
🟢 Gloo deployment status
   
Namespace        | Name                           | Ready | Status 
gloo-mesh        | gloo-mesh-agent                | 1/1   | Healthy
gloo-mesh        | gloo-mesh-mgmt-server          | 1/1   | Healthy
gloo-mesh        | gloo-mesh-redis                | 1/1   | Healthy
gloo-mesh        | gloo-mesh-ui                   | 1/1   | Healthy
gloo-mesh        | prometheus-server              | 1/1   | Healthy
gloo-mesh-addons | ext-auth-service               | 1/1   | Healthy
gloo-mesh-addons | gloo-mesh-portal-server        | 1/1   | Healthy
gloo-mesh-addons | rate-limiter                   | 1/1   | Healthy
gloo-mesh-addons | redis                          | 1/1   | Healthy
gloo-mesh        | gloo-telemetry-collector-agent | 3/3   | Healthy

🟢 Mgmt server connectivity to workload agents

Cluster  | Registered | Connected Pod                                   
cluster1 | true       | gloo-mesh/gloo-mesh-mgmt-server-65bd557b95-v8qq6