Skip to content

Latest commit

 

History

History
105 lines (77 loc) · 5.33 KB

webhooks.md

File metadata and controls

105 lines (77 loc) · 5.33 KB

Webhooks

A webhook is a POST request sent to a URL. Use webhooks to trigger an action in response to an event such as a repository push.

{% hint style="info" %} This functionality is only available in Portainer Business Edition. {% endhint %}

{% hint style="info" %} Webhooks are only available on non-Edge environments (environments running Portainer Server or Portainer Agent, not the Portainer Edge Agent). This is because the tunnel to the Portainer Edge Agent is only opened on-demand, and therefore would mean there is no way to expose a webhook permanently. {% endhint %}

Enabling an application webhook

From the menu select Applications then select the application that you want to configure the webhook for. Then select the Edit this application button.

{% hint style="info" %} Webhooks are only available for applications deployed from a Git repository. {% endhint %}

Enable GitOps updates if it is not already enabled and select Webhook as the Mechanism. When the URL appears, click Copy link. This is the URL used to trigger the webhook.

This example shows how to trigger the webhook:

<form action="https://portainer:9443/api/stacks/webhooks/40ac1662-47c3-4a8e-b148-2a34eb52bb42" method="post">
  Redeploy application <input type="submit" />
</form>

Using environment variables with webhooks

When triggering a webhook, environment variables can be passed through the endpoint and referenced within the deployment.

{% hint style="info" %} Environment variables can not be updated for Pods, only for Deployments. {% endhint %}

To specify an environment variable on a webhook, add it as a variable to the URL. For example, to pass a SERVICE_TAG variable with the value development:

https://portainer:9443/api/stacks/webhooks/40ac1662-47c3-4a8e-b148-2a34eb52bb42?SERVICE_TAG=development

To reference the SERVICE_TAG variable in your manifest with a fallback to the value stable:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 2
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80
        env:
        - name: SERVICE_TAG 
          value: "stable"

{% hint style="warning" %} Environment variables must already be defined in the manifest - new environment variables cannot be added via the webhook. {% endhint %}

Rolling restarts

When using an application's webhook to redeploy your application, you can tell Portainer to perform a rolling restart of the application rather than a "terminate and restart" redeploy.

{% hint style="info" %} This functionality is only available in Portainer Business Edition. {% endhint %}

To specify this, use the rollout-restart parameter in your webhook call:

https://portainer:9443/api/stacks/webhooks/40ac1662-47c3-4a8e-b148-2a34eb52bb42?rollout-restart=all

Valid options are as below:

Option Overview
rollout-restart=all All of the application's deployments will be redeployed as a rolling restart.
rollout-restart=deployment/deployment1,deployment/deployment2

Only the specified deployment(s) will be redeployed as a rolling restart. All other deployments will not be redeployed or restarted. Separate multiple deployments with commas.
This option supports Deployments (deployment/deployment1), DaemonSets (daemonset/daemonset1), and StatefulSets (statefulset/statefulset1).

If the rollout-restart parameter is not defined, the webhook will redeploy the application in traditional "terminate and restart" behavior.

{% hint style="warning" %} If your cluster has a change window enabled, the rolling restart will only be performed within the change window. {% endhint %}