Skip to main content

Deploying the On-premise Agent

Set up a secure on-premise agent faster than you can say it

The On-premise Agent enables users to secure their workloads inside their own infrastructure. Getting set up with an on-premise agent for Superblocks is an extremely simple process.

On this page:

  1. Prerequisites
  2. 5 min Quickstart Guide
  3. Environments
  4. Deployment Guidelines
  5. Upgrading
  6. Supported Platforms

Prerequisites​

The On-Premise Agent requires about 200MB of memory running at a steady state. Provisioning 1GB of memory for the agent is recommended but may need to be adjusted based on your workload. Provisioning with less can potentially cause your agent to hit Out Of Memory errors.

5 min Quickstart Guide​

  1. Navigate to the On-Premise Agents section in Superblocks. If you have existing On-premise Agents, information about them will be displayed in the list. If not, you view instructions to add one by simply clicking the View deployment instructions button.

Arrow pointing to View deployment instructions button

2. This will open up a modal displaying the necessary steps to deploy your OPA. You can customize these steps with your own configuration by modifying the form at the top of the modal.

info

We currently support Docker, Helm, AWS, GCP, Azure and Digital Ocean with more deployment options coming soon. Email help@superblockshq.com if your infrastructure is not supported

Arrow pointing to Agent URL

3. Execute the documented instructions to deploy your new OPA.

Commands to install the Superblocks on premise agent are provided in app

4. You can monitor the agent's deployment status at the bottom of the modal.

Waiting for superblocks on premise agent to connect

When the agent is able to connect to the Superblocks server, you will see the status updated to reflect the successful registration.

info

If you don't see the Success message after deploying your agent, try clicking the Refresh Button beside "Waiting to connect to a new agent"

Successfully deployed on premise agent as seen within the UI

5. Close the modal and view the status of your deployed agents

List of active and disconnected agents by version

6. To start directing workloads to your On-premise Agents, toggle the slider On. Now all requests to your Integrations will flow through your On-premise Agents instead of the Superblocks Cloud, securing your customer data inside your network.

Toggle switch to select between using on premise agents or cloud agents

Environments​

We recommend agents workloads to be separated by environment. You are able to specify specific agents to only handle production workloads and specific agents to only handle staging workloads. These production-only agents can be set up in isolated networks / VPCs with resources provisioned separately from staging. This ensures production performance and security are not compromised by any staging workloads.

To assign environment-specific agents, you can select an environment in the deployment modal. This will append the environment variable SUPERBLOCKS_AGENT_ENVIRONMENT to your deployment instructions. If not set, by default, agents are allocated to all environments. This means the agent will handle workloads from both staging and production integrations.

Chose which agents should handle staging and production requests

Deployment Guidelines​

If you're deploying the OPA in a different location and/or updating its host URL, you can override the SUPERBLOCKS_AGENT_HOST_URL environment variable with the appropriate value in the format of <agent-url>/agent.

Upgrading​

Upgrading your agent is even simpler - you can always pull the latest version of the OPA using the latest tag. All other configuration details (ID, key, URL, etc) remain the same.

Supported Platforms​

Follow the instructions below to deploy the agent for your preferred platform (Helm is recommended). Note, the agent key can be obtained by clicking View deployment instructions on the On-premise Agents page.

info

If your organization doesn't use Helm to manage Kubernetes resources, you can still install the Helm CLI and use it to generate the manifest templates to deploy directly.

1. Add the chart repository

helm repo add superblocks https://charts.superblocks.com/superblocks
helm repo update

2. Deploy the chart and check rollout status

helm upgrade -i -n superblocks superblocks-agent superblocks/superblocks-agent \
  --create-namespace \
  --set superblocks.agentKey='<agent-key>' # obtained during agent onboarding \
  --set superblocks.agentHostUrl='http[s]://<agent-host[:port]>/agent' \
  --set superblocks.agentEnvironment='<"*"|"staging"|"production">'
kubectl -n superblocks rollout status deploy/superblocks-agent-controller -w

Note, theagentHostURL should be either:

  • http://localhost:8020/agent - For testing a local setup where your browser is connected/forwarded to the same network as the agent. For example, if you've deployed the agent with Docker or Minikube on your laptop, and connect to Superblocks from the browser on that device or you're using port-forwarding to connect from localhost to your Kubernetes cluster.

    or

  • https://<DNS_ADDRESS>/agent - In non-localhost production settings, the agent's service must be exposed externally, typically via an ingress controller and load balancer. You can then set the agent URL to the DNS of the load balancer, or an external DNS that routes to the load balancer.

3. Allow access from the browser

For testing, use the command below to forward connections from your local browser to the agent.

kubectl -n superblocks port-forward deploy/superblocks-agent-controller 8020

For production deployments, it is recommended to expose the agent service by enabling Ingress as described below.

4. Configure additional settings in values.yaml

Beyond the default settings, a comprehensive list of configurations can be found in the agent's Helm chart repo. Use this as a template to copy to your own locally kept values.yaml with additional configuration as required.

For example, in a non-localhost production or cloud hosted scenario, we recommend enabling Ingress in the Helm chart as follows:

controller:

  service:
    type: ClusterIP
    port: 8020

  ingress:
    enabled: true
    class: "" # nginx
    annotations: {}
      # kubernetes.io/tls-acme: "true"
    hosts:
      - host: example-host.com
        paths:
          - /agent
          - /health
    tls: []
    # - secretName: chart-example-tls
    #   hosts:
    #     - example-host.com

After making any changes to values.yaml, redeploy the chart.

helm upgrade -i -n superblocks superblocks-agent superblocks/superblocks-agent \
  --create-namespace \
  -f values.yaml \
  --set superblocks.agentKey='<agent-key>' # obtained during agent onboarding \
  --set superblocks.agentHostUrl='http[s]://<agent-host[:port]>/agent' \
  --set superblocks.agentEnvironment='<"*"|"staging"|"production">'