> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Manage your Kubernetes deployments

This guide demonstrates how to bring your Kubernetes deployment management experience into Port. You will learn how to:

  • Ingest Kubernetes cluster, deployment, and pod data into Port's software catalog using Port's Kubernetes integration.
  • Set up self-service actions to manage Kubernetes deployments and pods by restarting deployments, changing replica counts, and deleting pods.
Port dashboard listing Kubernetes deployments

Common use cases​

  • Monitor the status and health of all Kubernetes deployments and pods across clusters from a single interface.
  • Provide self-service capabilities for developers to restart deployments, change replica counts, and manage pods.

Prerequisites​

This guide assumes the following:

Dedicated Workflows Repository

We recommend creating a dedicated repository for the workflows that are used by Port actions.

Set up self-service actions​

We will create self-service actions to manage your Kubernetes deployments and pods directly from Port using GitHub Actions. We will implement workflows to:

  1. Restart a Kubernetes deployment.
  2. Change a Kubernetes deployment replica count.
  3. Delete a Kubernetes pod.

To implement these use-cases, follow the steps below:

Add GitHub secrets​

In your GitHub repository, go to Settings > Secrets and add the following secrets:

  • PORT_CLIENT_ID - Port Client ID learn more.
  • PORT_CLIENT_SECRET - Port Client Secret learn more.
  • MY_GITHUB_TOKEN - a classic personal access token with repository access. This is required only for the replica count workflow because it opens and optionally merges a pull request.

Configure Kubernetes authentication​

Choose one of the following authentication methods based on your cluster setup:

This approach uses Google Cloud's authentication for GKE clusters.

  1. Create a GCP service account in the Google Cloud Console:

    • Go to IAM & Admin → Service Accounts.
    • Click Create Service Account.
    • Name it github-actions and add a description.
    • Grant the following roles:
      • Kubernetes Engine Cluster Viewer (roles/container.clusterViewer).
      • Kubernetes Engine Admin (roles/container.admin).

  2. Create a service account key:

    • In the service account details, go to the Keys tab.
    • Click Add Key → Create new key.
    • Choose JSON format and download the key file.

  3. Add to GitHub secrets:

    • GCP_SERVICE_ACCOUNT_KEY - The service account key JSON (minified to a single line).
    • GCP_CLUSTER_LOCATION - The location of your cluster.
Minifying JSON for GitHub Secrets

To avoid aggressive log sanitization, minify your service account JSON into a single line before storing it as a GitHub secret. You can use an online tool or the following command to minify the json:

jq -c '.' your-service-account-key.json | pbcopy

Restart a Kubernetes deployment​

Add GitHub workflow

Create the file .github/workflows/restart-k8s-deployment.yaml in the .github/workflows folder of your repository.

Restart GKE Deployment GitHub workflow (Click to expand)
name: Restart GKE Deployment

on:
  workflow_dispatch:
    inputs:
      port_context:
        required: true
        description: 'Action and general context (blueprint, entity, run id, etc...)'
        type: string

jobs:
  restart-deployment:
    runs-on: ubuntu-latest
    steps:
      - uses: 'actions/checkout@v6'
      
      - name: Inform Port of workflow start
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.port.io
          operation: PATCH_RUN
          runId: ${{fromJson(inputs.port_context).runId}}
          logMessage: Configuring GCP credentials to restart GKE deployment ${{ fromJson(inputs.port_context).entity.title }}

      - id: 'auth'
        uses: 'google-github-actions/auth@v2'
        with:
          credentials_json: '${{ secrets.GCP_SERVICE_ACCOUNT_KEY }}'

      - id: 'get-credentials'
        uses: 'google-github-actions/get-gke-credentials@v2'
        with:
          cluster_name: ${{ fromJson(inputs.port_context).entity.properties.Cluster }}
          location: '${{ secrets.GCP_CLUSTER_LOCATION }}'
          
      - name: Restart Kubernetes deployment
        run: |
          kubectl rollout restart deployment/${{ fromJson(inputs.port_context).entity.identifier }} -n ${{ fromJson(inputs.port_context).entity.relations.Namespace }}
          
      - name: Wait for deployment rollout
        run: |
          kubectl rollout status deployment/${{ fromJson(inputs.port_context).entity.identifier }} -n ${{ fromJson(inputs.port_context).entity.relations.Namespace }} --timeout=300s
          
      - name: Inform Port about deployment restart success
        if: success()
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.port.io
          operation: PATCH_RUN
          runId: ${{ fromJson(inputs.port_context).runId }}
          status: 'SUCCESS'
          logMessage: ✅ GKE deployment ${{ fromJson(inputs.port_context).entity.title }} restarted successfully
          summary: GKE deployment restart completed successfully

      - name: Inform Port about deployment restart failure
        if: failure()
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.port.io
          operation: PATCH_RUN
          runId: ${{ fromJson(inputs.port_context).runId }}
          status: 'FAILURE'
          logMessage: ❌ Failed to restart GKE deployment ${{ fromJson(inputs.port_context).entity.title }}
          summary: GKE deployment restart failed

Create Port action

  1. Go to the Self-service page of your portal.

  2. Click on the + New Action button.

  3. Click on the {...} Edit JSON button.

  4. Copy and paste the following JSON configuration into the editor.

    Restart Kubernetes deployment action (Click to expand)
    Replace the variables
    • <YOUR_GITHUB_OCEAN_INTEGRATION_ID> - your GitHub Ocean integration installation ID.
    • <GITHUB-ORG> - your GitHub organization or user name.
    • <GITHUB-REPO> - your GitHub repository name.
    {
      "identifier": "restart_k8s_deployment",
      "title": "Restart Kubernetes Deployment",
      "icon": "Cluster",
      "description": "Restart a Kubernetes deployment to trigger a rolling update",
      "trigger": {
        "type": "self-service",
        "operation": "DAY-2",
        "userInputs": {
          "properties": {},
          "required": []
        },
        "blueprintIdentifier": "workload"
      },
      "invocationMethod": {
        "type": "INTEGRATION_ACTION",
        "installationId": "<YOUR_GITHUB_OCEAN_INTEGRATION_ID>",
        "integrationActionType": "dispatch_workflow",
        "integrationActionExecutionProperties": {
          "org": "<GITHUB-ORG>",
          "repo": "<GITHUB-REPO>",
          "workflow": "restart-k8s-deployment.yaml",
          "workflowInputs": {
            "port_context": {
              "entity": "{{ .entity }}",
              "runId": "{{ .run.id }}"
            }
          },
          "reportWorkflowStatus": true
        }
      },
      "requiredApproval": false
    }

  5. Click Save.

Now you should see the Restart Kubernetes Deployment action in the self-service page. 🎉

Change deployment replica count​

This action updates the replica count in your Kubernetes deployment manifest and opens a GitHub pull request with the change. You can also let the workflow merge the pull request automatically.

Add GitHub workflow

Create the file .github/workflows/change-replica-count.yaml in the .github/workflows folder of your repository.

Change replica count GitHub workflow (Click to expand)
Replace the variables
  • <DEPLOYMENT-MANIFEST-PATH> - the path to the Kubernetes deployment manifest, such as app/deployment.yaml.
  • <REPLICA-PROPERTY-PATH> - the path to the replica count field in the deployment manifest, such as spec.replicas.
name: Change Replica Count

on:
  workflow_dispatch:
    inputs:
      replica_count:
        description: The new replica count for the deployment
        required: true
        type: string
      auto_merge:
        description: Whether the created PR should be merged automatically
        required: true
        type: boolean
      port_context:
        required: true
        description: >-
          Port's payload, including details for who triggered the action and
          general context (blueprint, run id, etc...)

jobs:
  change-replica-count:
    runs-on: ubuntu-latest
    steps:
      - name: Inform Port about replica count request
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.port.io
          operation: PATCH_RUN
          runId: ${{ fromJson(github.event.inputs.port_context).runId }}
          logMessage: About to change replica count in deployment manifest

      - uses: actions/checkout@v6

      - name: Create pull request
        id: create-pr
        uses: fjogeleit/yaml-update-action@main
        with:
          valueFile: '<DEPLOYMENT-MANIFEST-PATH>'
          propertyPath: '<REPLICA-PROPERTY-PATH>'
          value: "!!int '${{ github.event.inputs.replica_count }}'"
          commitChange: true
          token: ${{ secrets.MY_GITHUB_TOKEN }}
          targetBranch: main
          masterBranchName: main
          createPR: true
          branch: deployment/${{ fromJson(github.event.inputs.port_context).runId }}
          message: 'Update deployment replica to ${{ github.event.inputs.replica_count }}'

      - name: Inform Port about pull request creation success
        if: steps.create-pr.outcome == 'success'
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.port.io
          operation: PATCH_RUN
          runId: ${{ fromJson(github.event.inputs.port_context).runId }}
          logMessage: |
            Pull request was created successfully: ${{ fromJson(steps.create-pr.outputs.pull_request).html_url }}
          link: '["${{ fromJson(steps.create-pr.outputs.pull_request).html_url }}"]'

      - name: Inform Port about pull request creation failure
        if: steps.create-pr.outcome != 'success'
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.port.io
          operation: PATCH_RUN
          runId: ${{ fromJson(github.event.inputs.port_context).runId }}
          status: FAILURE
          logMessage: Pull request creation failed

      - name: Merge pull request
        if: ${{ github.event.inputs.auto_merge == 'true' && steps.create-pr.outcome == 'success' }}
        env:
          GH_TOKEN: ${{ secrets.MY_GITHUB_TOKEN }}
          PR_URL: ${{ fromJson(steps.create-pr.outputs.pull_request).url }}
        run: |
          HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
            -X PUT \
            -H "Accept: application/vnd.github+json" \
            -H "Authorization: Bearer $GH_TOKEN" \
            "$PR_URL/merge")

          echo "HTTP Status: $HTTP_STATUS"

          if [ "$HTTP_STATUS" -eq 200 ]; then
            echo "Pull request merged successfully."
            echo "merge_status=successful" >> "$GITHUB_ENV"
          else
            echo "Failed to merge PR. HTTP Status: $HTTP_STATUS"
            echo "merge_status=unsuccessful" >> "$GITHUB_ENV"
          fi

      - name: Inform Port about replica update completion
        if: ${{ github.event.inputs.auto_merge == 'true' }}
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.port.io
          operation: PATCH_RUN
          runId: ${{ fromJson(github.event.inputs.port_context).runId }}
          logMessage: Pull request merge was ${{ env.merge_status }}

Set up self-service action

Follow the steps below to create a self-service action that triggers the GitHub workflow.

  1. Go to the Self-service page of your portal.

  2. Click on the + New Action button.

  3. Click on the {...} Edit JSON button.

  4. Copy and paste the following JSON configuration into the editor:

    Change deployment replica count action (Click to expand)
    Replace the variables
    • <YOUR_GITHUB_OCEAN_INTEGRATION_ID> - your GitHub Ocean integration installation ID.
    • <GITHUB-ORG> - your GitHub organization or user name.
    • <GITHUB-REPO> - your GitHub repository name.
    {
      "identifier": "change_deployment_replica_count",
      "title": "Change deployment replica count",
      "icon": "GithubActions",
      "trigger": {
        "type": "self-service",
        "operation": "DAY-2",
        "userInputs": {
          "properties": {
            "replica_count": {
              "icon": "DefaultProperty",
              "title": "Number of replicas",
              "type": "number"
            },
            "auto_merge": {
              "title": "Auto merge",
              "type": "boolean",
              "default": false,
              "description": "Whether the created pull request should be merged automatically"
            }
          },
          "required": [
            "replica_count"
          ],
          "order": [
            "replica_count",
            "auto_merge"
          ]
        },
        "blueprintIdentifier": "workload"
      },
      "invocationMethod": {
        "type": "INTEGRATION_ACTION",
        "installationId": "<YOUR_GITHUB_OCEAN_INTEGRATION_ID>",
        "integrationActionType": "dispatch_workflow",
        "integrationActionExecutionProperties": {
          "org": "<GITHUB-ORG>",
          "repo": "<GITHUB-REPO>",
          "workflow": "change-replica-count.yaml",
          "workflowInputs": {
            "replica_count": "{{ .inputs.\"replica_count\" }}",
            "auto_merge": "{{ .inputs.\"auto_merge\" }}",
            "port_context": {
              "entity": "{{ .entity.identifier }}",
              "blueprint": "{{ .action.blueprint }}",
              "runId": "{{ .run.id }}",
              "trigger": "{{ .trigger }}"
            }
          },
          "reportWorkflowStatus": true
        }
      },
      "requiredApproval": false
    }

  5. Click Save to create the action.

Test the flow

  1. Go to the Self-service page of your portal.

  2. Execute the "Change deployment replica count" action on a workload.

  3. Enter the new replica count and choose whether to auto-merge the pull request.

  4. Verify that GitHub creates the pull request and that Port tracks the action run.

Merged GitHub PR updating replica count

Delete a Kubernetes pod​

Add GitHub workflow

Create the file .github/workflows/delete-k8s-pod.yaml in the .github/workflows folder of your repository.

Delete GKE Pod GitHub workflow (Click to expand)
name: Delete GKE Pod

on:
  workflow_dispatch:
    inputs:
      port_context:
        required: true
        description: 'Action and general context (blueprint, entity, run id, etc...)'
        type: string

jobs:
  delete-pod:
    runs-on: ubuntu-latest
    steps:
      - uses: 'actions/checkout@v6'
      
      - name: Inform Port of workflow start
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.port.io
          operation: PATCH_RUN
          runId: ${{fromJson(inputs.port_context).runId}}
          logMessage: Configuring GCP credentials to delete GKE pod ${{ fromJson(inputs.port_context).entity.title }}

      - id: 'auth'
        uses: 'google-github-actions/auth@v2'
        with:
          credentials_json: '${{ secrets.GCP_SERVICE_ACCOUNT_KEY }}'

      - name: Set up Cloud SDK
        uses: google-github-actions/setup-gcloud@v2

      - id: 'get-credentials'
        uses: 'google-github-actions/get-gke-credentials@v2'
        with:
          cluster_name: ${{ fromJson(inputs.port_context).entity.properties.Cluster }}
          location: '${{ secrets.GCP_CLUSTER_LOCATION }}'
        
      - name: Delete Kubernetes pod
        run: |
          kubectl delete pod ${{ fromJson(inputs.port_context).entity.identifier }} -n ${{ fromJson(inputs.port_context).entity.properties.namespace }}
          
      - name: Inform Port about pod deletion success
        if: success()
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.port.io
          operation: PATCH_RUN
          runId: ${{ fromJson(inputs.port_context).runId }}
          status: 'SUCCESS'
          logMessage: ✅ GKE pod ${{ fromJson(inputs.port_context).entity.title }} deleted successfully
          summary: GKE pod deletion completed successfully

      - name: Inform Port about pod deletion failure
        if: failure()
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.port.io
          operation: PATCH_RUN
          runId: ${{ fromJson(inputs.port_context).runId }}
          status: 'FAILURE'
          logMessage: ❌ Failed to delete GKE pod ${{ fromJson(inputs.port_context).entity.title }}
          summary: GKE pod deletion failed

Create Port action

  1. Go to the Self-service page of your portal.

  2. Click on the + New Action button.

  3. Click on the {...} Edit JSON button.

  4. Copy and paste the following JSON configuration into the editor.

    Delete Kubernetes pod action (Click to expand)
    Replace the variables
    • <YOUR_GITHUB_OCEAN_INTEGRATION_ID> - your GitHub Ocean integration installation ID.
    • <GITHUB-ORG> - your GitHub organization or user name.
    • <GITHUB-REPO> - your GitHub repository name.
    {
      "identifier": "delete_k8s_pod",
      "title": "Delete Kubernetes Pod",
      "icon": "Cluster",
      "description": "Delete a Kubernetes pod (will be recreated by the deployment)",
      "trigger": {
        "type": "self-service",
        "operation": "DELETE",
        "userInputs": {
          "properties": {},
          "required": []
        },
        "blueprintIdentifier": "pod"
      },
      "invocationMethod": {
        "type": "INTEGRATION_ACTION",
        "installationId": "<YOUR_GITHUB_OCEAN_INTEGRATION_ID>",
        "integrationActionType": "dispatch_workflow",
        "integrationActionExecutionProperties": {
          "org": "<GITHUB-ORG>",
          "repo": "<GITHUB-REPO>",
          "workflow": "delete-k8s-pod.yaml",
          "workflowInputs": {
            "port_context": {
              "entity": "{{ .entity }}",
              "runId": "{{ .run.id }}"
            }
          },
          "reportWorkflowStatus": true
        }
      },
      "requiredApproval": false
    }

  5. Click Save.

Now you should see the Delete Kubernetes Pod action in the self-service page. 🎉