Skip to main content

Check out Port for yourself 

Enrich services using Gitops

This guide takes 10 minutes to complete, and aims to demonstrate Port's flexibility when working with Gitops.

Prerequisites
  • This guide assumes you have a Port account and that you have finished the onboarding process. We will use the Service blueprint that was created during the onboarding process.
  • You will need a Git repository (Github, GitLab, or Bitbucket) in which you can place a workflow/pipeline that we will use in this guide. If you don't have one, we recommend creating a new repository named Port-actions.

The goal of this guide​

In this guide we will enrich a service in Port using Gitops. In reality, this can be used by developers to independently add additional valuable data about their services to Port.

After completing it, you will get a sense of how it can benefit different personas in your organization:

  • Developers will be able to enrich their services without needing to nag devops engineers.
  • Platform engineers will be able to create RBAC-controlled actions for developers, empowering their independence.
  • R&D managers will be able to track additional, valuable data about services in the organization.

Add new properties to your Service blueprint​

Let's start by adding two new properties to the Service blueprint, that we will later populate using Gitops.

  1. Go to your Builder, expand the Service blueprint, and click on New property.

  2. The first property will be the service's type, chosen from a predefined list of options. Fill out the form like this, then click Create:

  3. The second property will be the lifecycle state of the service, also chosen from a predefined list of options. Fill out the form like this, then click Create:

    Note the colors of the inputs, this will make it easier to see a service's lifecycle in your catalog 😎

Model domains for your services​

Services that share a business purpose (e.g. payments, shipping) are often grouped together using domains. Let's create a blueprint to represent a domain in Port:

  1. In your Builder, click on the + Blueprint button:

  2. Click on the Edit JSON button in the top right corner, replace the content with the following definition, then click Create:

    Blueprint JSON (click to expand)
    {
      "identifier": "domain",
      "title": "Domain",
      "icon": "TwoUsers",
      "schema": {
        "properties": {
          "architecture": {
            "title": "Architecture",
            "type": "string",
            "format": "url",
            "spec": "embedded-url"
          }
        },
        "required": []
      },
      "mirrorProperties": {},
      "calculationProperties": {},
      "relations": {}
    }

Connect your services to their domains​

Now that we have a blueprint to represent a domain, let's connect it to our services. We will do this by adding a relation to the Service blueprint:

  1. Go to your Builder, expand the Service blueprint, and click on New relation:

  2. Fill out the form like this, then click Create:



Create domains via Gitops​

Now that we have a Domain blueprint, we can create some domains in Port. This can be done manually from the UI, or via Gitops which is the method we will use in this guide.

  1. In your Port-actions (or equivalent) Github repository, create a new file named port.yml in the root directory, and use the following snippet as its content:

    port.yml (click to expand)
    - identifier: payment
      title: Payment
      blueprint: domain
      properties:
        architecture: https://lucid.app/documents/embedded/c3d64493-a5fe-4b18-98d5-66d355080de3
    - identifier: shipping
      title: Shipping
      blueprint: domain
      properties:
        architecture: https://lucid.app/documents/embedded/c3d64493-a5fe-4b18-98d5-66d355080de3

  2. Head back to your software catalog, you will see that Port has created two new domain entities:

The architecture property is a URL to a Lucidchart diagram. This is a handy way to track a domain's architecture in your software catalog.


Create an action to enrich services​

As platform engineers, we want to enable our developers to perform certain actions on their own. Let's create an action that developers can use to add data to a service, and allocate it to a domain.

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

  2. Click on the + Action button in the top-right corner :

  3. Fill the basic form with the following:

    • Title: Enter Enrich service

    • Identifier Toggle the switch icon off and type a service_enrich_service

    • Description: Enter the description (e.g., Enrich service with data )

    • Icon: Type Git and choose the Icon (optional)

    • Operation: Choose Day-2 from the dropdown

    • Blueprint: Choose Service from the dropdown


  4. Click on Next, and add the Domain input:

    • Click on + Input.

    • Enter the Title Domain.

    • Select the Type Entity selection.

    • Add the Description (optional).

    • Set Required to True.

    • Select Domain as the Blueprint

    • Click on the Create button.


      Entity selection input type

      The Entity selection type allows the executing user to choose an entity directly from the catalog.

  5. Click on Next to configure the Backend.

Define backend type​

Now we'll define the backend of the action. Port supports multiple invocation types, for this tutorial we will use a Github workflow, a GitLab pipeline, or a Jenkins pipeline (choose this option if you are using Bitbucket).

Note that you will need to have Port's Github app installed in your Github organization (the one that contains the repository you'll work with).

Fill out the form with your values:

  • Replace the Organization and Repository values with your values (this is where the workflow will reside and run).

  • Name the workflow port-enrich-service.yml.

  • Fill out your workflow details:

  • Scroll down to the Configure the invocation payload section.
    This is where you can define which data will be sent to your backend each time the action is executed.

    For this example, we will send some details that our backend needs to know - the user inputs, the entity, and the id of the action run.
    Copy the following JSON snippet and paste it in the payload code box:

    {
      "port_context": {
        "entity": "{{ .entity.identifier }}",
        "runId": "{{ .run.id }}"
      },
      "domain": "{{ .inputs.domain.identifier }}",
      "type": "{{ .inputs.type }}",
      "lifecycle": "{{ .inputs.lifecycle }}"
    }

The last step is customizing the action's permissions. For simplicity's sake, we will use the default settings. For more information, see the permissions page. Click Create.

Setup the action's backend​

Our action will create a pull-request in the service's repository, containing a port.yml file that will add data to the service in Port. Choose a backend type below to setup the workflow:

  1. First, let's create the necessary token and secrets. If you've already completed the scaffold a new service guide, you should already have these configured and you can skip this step.

  • Go to your Github tokens page, create a personal access token with repo and admin:org scope, and copy it (this token is needed to create a pull-request from our workflow).

  • Go to your Port application, click on the ... in the top right corner, then click Credentials. Copy your Client ID and Client secret.

  1. In your Port-actions (or equivalent) Github repository, create 3 new secrets under Settings->Secrets and variables->Actions:

    • ORG_ADMIN_TOKEN - the personal access token you created in the previous step.
    • PORT_CLIENT_ID - the client ID you copied from your Port app.
    • PORT_CLIENT_SECRET - the client secret you copied from your Port app.

We will now create a YML file that will serve as a template for our services' port.yml configuration file.

  • In your repository, create a file named enrichService.yml under /templates/ (its path should be /templates/enrichService.yml).
  • Copy the following snippet and paste it in the file's contents:
enrichService.yml (click to expand)
# enrichService.yml

- identifier: "{{ service_identifier }}"
  blueprint: service
  properties:
    type: "{{ service_type }}"
    lifecycle: "{{ service_lifecycle }}"
  relations:
    domain: "{{ domain_identifier }}"

Now let's create the file that contains our logic:

In the same repository, under .github/workflows, create a new file named port-enrich-service.yml and use the following snippet as its content:

Github workflow (click to expand)
name: Enrich service
on:
  workflow_dispatch:
    inputs:
      port_context:
        required: true
        description: Includes the entity identifier and the action's run id
      domain:
        required: true
        description: The domain to assign the service to
        type: string
      type:
        required: true
        description: The type of the service
        type: string
      lifecycle:
        required: true
        description: The lifecycle state of the service
        type: string
jobs:
  enrichService:
    runs-on: ubuntu-latest
    steps:
      # Checkout the workflow's repository
      - uses: actions/checkout@v4
      # Checkout the service's repository
      - uses: actions/checkout@v4
        with:
          repository: "${{ github.repository_owner }}/${{ fromJson(inputs.port_context).entity }}"
          path: ./targetRepo
          token: ${{ secrets.ORG_ADMIN_TOKEN }}
      - name: Copy template yml file
        run: |
          cp templates/enrichService.yml ./targetRepo/port.yml
      - name: Update new file data
        run: |
          sed -i 's/{{ service_identifier }}/${{ fromJson(inputs.port_context).entity }}/' ./targetRepo/port.yml
          sed -i 's/{{ domain_identifier }}/${{ inputs.domain }}/' ./targetRepo/port.yml
          sed -i 's/{{ service_type }}/${{ inputs.type }}/' ./targetRepo/port.yml
          sed -i 's/{{ service_lifecycle }}/${{ inputs.lifecycle }}/' ./targetRepo/port.yml
      - name: Open a pull request
        uses: peter-evans/create-pull-request@v5
        with:
          token: ${{ secrets.ORG_ADMIN_TOKEN }}
          path: ./targetRepo
          commit-message: Enrich service - ${{ fromJson(inputs.port_context).entity}}
          committer: GitHub <noreply@github.com>
          author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>
          signoff: false
          branch: add-port-yml
          delete-branch: true
          title: Create port.yml - ${{ fromJson(inputs.port_context).entity }}
          body: |
            Add port.yaml to enrich service in Port.
          draft: false
      - name: Create a log message
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.getport.io
          operation: PATCH_RUN
          runId: ${{ fromJson(inputs.port_context).runId }}
          logMessage: Pull request to add port.yml created successfully for service "${{ fromJson(inputs.port_context).entity }}" 🚀
Selecting a Port API URL by account region

The baseUrl, port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters are used to select which instance or Port API will be used.

Port exposes two API instances, one for the EU region of Port, and one for the US region of Port.

The action is ready to be executed 🚀

Execute the action​

  1. After creating an action, it will appear under the Self-service page. Find your new Enrich service action, and click on Execute.

  2. Choose a service from the dropdown, a domain to assign it to, and any values for its type and lifecycle, then click Execute:

  3. A small popup will appear, click on View details:


This page provides details about the action run. We can see that the backend returned Success and the pull-request was created successfully.

  1. Head over to your service's repository, you will see that a new pull-request was created:

  2. Merge the pull-request, then head back to your software catalog.

  3. Find your service, and click on its identifier. This will take you to the service's catalog page, where you can see your new properties populated with data:


All done! 💪🏽

Possible daily routine integrations​

  • Fetch data from a Sentry project and reflect it in your software catalog.
  • Create and onboard services with a few clicks from your developer portal.

Conclusion​

Gitops is a common practice in modern software development, as it ensures that the state of your infrastructure is always in sync with your codebase.
Port allows you to easily integrate your Gitops practices with your software catalog, reflecting the state of your infrastructure, and allowing you to empower your developers with controlled actions.

More guides & tutorials will be available soon, in the meantime feel free to reach out with any questions via our community slack or Github project.