Navigation :

Administer the 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.

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.

Setup

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

Install

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

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

meshctl
Helm

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.3.22 sh -
export PATH=$HOME/.gloo-mesh/bin:$PATH

Install Gloo Gateway in your cluster. This command uses basic profiles to install the control 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 licensing.glooGatewayLicenseKey=$GLOO_GATEWAY_LICENSE_KEY
```

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, see Portal server.

cat >addons.yaml <<EOF
extAuthService:
  enabled: true
  extAuth:
    apiKeyStorage:
      # Use the local gloo-mesh-addons Redis for backing storage
      name: redis
      config:
        connection:
          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
    type: redis
    config:
      host: "redis.gloo-mesh-addons:6379"
    # Path for API key storage config file in the gloo-mesh-addons backing Redis
    configPath: /etc/redis/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 \
   --create-namespace \
   --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        | gloo-telemetry-gateway         | 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

Upgrade

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 -n gloo-mesh
```

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 \
   --set extAuthService.enabled=true \
   --set rateLimiter.enabled=true \
   --set glooPortalServer.enabled=true \
   --set glooPortalServer.apiKeyStorage.type=redis \
   --set glooPortalServer.apiKeyStorage.secretKey="ThisIsSecret" \
   --set glooPortalServer.apiKeyStorage.configPath="/etc/redis/config.yaml" \
   --set glooPortalServer.apiKeyStorage.config.host="redis.gloo-mesh-addons:6379" \
   --set extAuthService.extAuth.apiKeyStorage.name=redis \
   --set extAuthService.extAuth.apiKeyStorage.config.connection.host="redis.gloo-mesh-addons:6379" \
   --set extAuthService.extAuth.apiKeyStorage.config.connection.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 \
   --set extAuthService.enabled=true \
   --set rateLimiter.enabled=true \
   --set glooPortalServer.enabled=true \
   --set glooPortalServer.apiKeyStorage.type=redis \
   --set glooPortalServer.apiKeyStorage.secretKey="ThisIsSecret" \
   --set glooPortalServer.apiKeyStorage.configPath="/etc/redis/config.yaml" \
   --set glooPortalServer.apiKeyStorage.config.host="redis.gloo-mesh-addons:6379" \
   --set extAuthService.extAuth.apiKeyStorage.name=redis \
   --set extAuthService.extAuth.apiKeyStorage.config.connection.host="redis.gloo-mesh-addons:6379" \
   --set extAuthService.extAuth.apiKeyStorage.config.connection.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 -n gloo-mesh
```
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 > 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 > gloo-agent-addons.yaml
open gloo-agent-addons.yaml
```
Delete the first line that contains USER-SUPPLIED VALUES:, and save the file.

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
      config:
        connection:
          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
    type: redis
    config:
      host: "redis.gloo-mesh-addons:6379"
    # Path for API key storage config file in the gloo-mesh-addons backing Redis
    configPath: /etc/redis/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        | gloo-telemetry-gateway         | 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

Upgrade

You can follow the same procedure to upgrade Portal as you do for other Gloo Platform components.

Review the glooPortalServer* related Helm settings that you might want to upgrade. For example, you can upgrade the default values for resource requests and limits.
Follow the Upgrade guide.

Monitor

Check that your Gloo Platform Portal resources are running as expected.

Gloo Platform Portal has several different components that you set up, including the portal server, portal frontend app, ingress gateway, external auth server, rate limiter, and backing Redis database. Then, to configure Portal, you use different Gloo custom resources, including route tables and policies.

To help you monitor your environment, Gloo Platform provides several tools as follows:

Gloo UI, which features tabs to help debug your gateways, APIs, portals, and policies.
Global status reporting on Gloo custom resources, including whether the resource is accepted.
Logs for the deployments, such as the portal server or ingress gateway.
Troubleshooting documentation for the Gloo Platform add-ons.

Cleanup

Clean up the resources that you created in the Portal guides, but leave your installation running.

Delete the sample apps.

kubectl delete ns tracks
kubectl delete ns users
kubectl delete ns pets
kubectl delete ns store
kubectl delete -f https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-gateway/portal/frontend-deployment.yaml

Uninstall Keycloak as an in-cluster OIDC provider.
```
kubectl delete ns keycloak
```

Get all of the Gloo Portal-related custom resources.

kubectl get apidocs,ratelimitserverconfigs,RatelimitConfigs,ratelimitserversettings,ratelimitclientconfigs,ratelimitpolicies,extauthpolicies,extauthserver,routetables,portals,portalgroups,virtualgateways -A

Delete the custom resources, such as the following example.

kubectl delete -n gloo-mesh-gateways RouteTable tracks-rt
kubectl delete -n gloo-mesh-gateways RouteTable petstore-rt
kubectl delete -n gloo-mesh-gateways RouteTable api-example-com-rt
kubectl delete -n gloo-mesh-gateways RouteTable dev-portal-rt
kubectl delete -n gloo-mesh-gateways RouteTable portal-frontend
kubectl delete -n gloo-mesh-gateways VirtualGateway istio-ingressgateway-portal
kubectl delete -n default ExtAuthPolicy api-key-auth
kubectl delete -n gloo-mesh-addons ExtAuthPolicy oidc-auth
kubectl delete -n default Secret user1
kubectl delete -n gloo-mesh-addons Secret oauth
kubectl delete -n gloo-mesh-addons RateLimitClientConfig usage-plans
kubectl delete -n gloo-mesh-addons RateLimitServerConfig usage-plans
kubectl delete -n default RateLimitPolicy tracks-rate-limit
kubectl delete -n gloo-mesh-addons Portal developer-portal
kubectl delete -n gloo-mesh-addons PortalGroup petstore-group

Uninstall

You can follow the same procedure to uninstall Portal as you do for other Gloo Platform components.

For more information, see Uninstall.