Introduction

Welcome to the effx documentation site -- all the information you need to get the most out of the effx platform. If you're unfamiliar with effx, you can either learn more or sign up for a free trial.

For starters, check out our Getting Started guide to learn how to set up your effx and initial git integrations.

Documentation for building your own integration or interacting with our API is available in our API documentation.

If you're unable to get the help you need, please submit a support ticket at support@effx.com

Getting Started

Setting yourself up for success with effx starts with importing services. The easiest way to accomplish adding your first service to effx is by creating an effx.yaml file and importing it via one of our git-based integrations.

Learn the ins and outs of the effx.yaml format below, construct your first one, and set it up to be both validated and imported as part of your developer routine.

Building your first service effx.yaml

---
version: effx/v1
kind: service
spec:
  name: example-service
  description: example description for the example-service
  annotations:
    effx.io/owned-by: example-team
  tags:
    group: example
    tier: 1
    go: 1.15.5
  contact:
    email: support@effx.com
    chat:
      label: "#community"
      url: https://m11s.slack.com/archives/C01E19PPKNH
    onCall:
      label: "pagerduty schedule"
      url: https://docs.effx.com/#oncall-links
  linkGroups:
    - label: Dashboards
      links:
        - label: Datadog
          url: https://app.datadoghq.com/dashboard/y2w-wt6-wi8/effx-platform-status
    - label: Runbooks
      links:
        - label: Runbook
          url: https://blog.effx.com/how-to-write-a-runbook/
    - label: Version Control
      links:
        - label: GitHub
          url: https://github.com/effxhq/effx-sync-action
    - label: Documentation
      links:
        - label: API Documentation
          url: https://docs.effx.com/#api-documentation
  dependencies:
    manual:
      # Both describe dependencies on other services by name
      - kind: service
        name: arrakis
      - name: caladan

The effx.yaml file is the source of truth for your services within effx. The format is as follows:

Within the spec portion of the Service definition, you can define the following:

• name - This is the name of the service which is the primary way the service will be displayed
• description - The description is a string describing what the service does -- engineers will be able to discover the service by searching for terms in the description
• annotations - Annotations are used to provide structured data within effx:
  • effx.io/owned-by - denote the team that owns the service
• tags - This is the primary way to create and provide values for the taxonomy of your service. They're free form so you can choose what makes the most sense for your organization. Some commonly-tags are group to denote a group of services, tier to denote the priority or importance of a service, and items to denote language e.g. go with a value of 1.15.5 like in the example.
• contact - Provide contact information for a particular service. Available contact types are:
  • email - email address for who to contact about the service
  • onCall - link to the on-call rotation for the service
  • chat - link to the best chat room to discuss issues with the service
  • issueTracker - where to file bugs for the service
• linkGroups - Link Groups provide you the ability to organize links to external services or tools where you can find more information about a service. Common linkGroups are:
  • dashboards - where to find observability dashboards (APM, tracing, logging)
  • version control - where is the repository for this service
  • documentation - where is the service's documentation or API
  • runbooks - where are the runbooks for the service?
  • linkGroups are flexible, so you can use them however makes sense to structure your links in the user interface. You can provide multiple links structures per linkGroup, each requiring a label and url. The label appears on the button for the link within the user interface. You can also use the YAML Wizard to generate your effx.yaml, modify the values in the example-service or hand craft your own YAML if you're comfortable.
• dependencies - Define dependencies on other services
  • manual - A section for explicit declarations (array). Each dependency has a kind of entity to depend on (defaults to "service") & a name which matches a dependency by the kind's name

Building your first team effx.yaml

---
version: effx/v1
kind: team
spec:
  name: example team
  description: awesome team responsible for example services
  annotations:
    effx.io/reports-to: engineering
  contact:
    email: support@effx.com
    chat:
      label: "#community"
      url: https://m11s.slack.com/archives/C01E19PPKN
    onCall:
      label: "pagerduty schedule"
      url: https://docs.effx.com/#oncall-links

The effx.yaml file can also be used to create teams within the effx platform. We suggest naming the file teamname.effx.yaml or teams.effx.yaml if you're adding all teams via one file.

Within the spec portion of the Team definition, you can define the following:

• name - This is the name of the team which is the primary way the team will be displayed
• description - The description is a string describing what the team does
• annotations - Annotations are used to provide structured data within effx:
  • effx.io/reports-to - denote the team that this team folds into for hierarchy purposes
• tags - This is the primary way to create and provide values for the taxonomy of your service. They're free form so you can choose what makes the most sense for your organization. Some commonly-tags are group to denote a group of services, tier to denote the priority or importance of a service, and items to denote language e.g. go with a value of 1.15.5 like in the example.
• contact - Provide contact information for a particular service. Available contact types are:
  • email - email address for the team
  • onCall - link to the on-call rotation for the team
  • chat - link to the best chat room to contact the team
  • issueTracker - where to file bugs for the team

Uploading effx.yaml definitions

Fundamentally, uploading a resource definition means sending effx.yaml file contents to our API. We've provided a CLI to simplify this process. Our automations leverage the CLI to upload your resource definitions.

effx recommends using a GitOps workflow to upload resource definitions. Configure automated file uploads in the following section.

Automations

effx was built to support a GitOps workflow. Create your resource definitions in your preferred editor or use the platform's wizard. Get your definitions peer-reviewed and upon approval, these definitions are uploaded to our platform via Continous Integration.

We've built out some automations for your reference. Use them as-is or customize for your workflow!

Using Github Actions

Automate syncing services to effx with Github Actions

We’ll walk you through how to set up a workflow that uses both of effx’s published Github Lint and Sync Actions, which will help you quickly and reliably bring your service effx.yaml files into effx.

Note: You’ll need to configure the Secret API Key before setting up the workflow. This requires admin access to the services’ Github repository.

Configure the Secret API Key

Setup your effx API key within the repo's Github Secrets so that the workflow we’ll set up next has the right credentials to access our effx API.

1. Navigate to the repository's Settings in the Github web interface

2. Select Secrets from the left side menu, and create a New Secret

3. Type EFFX_API_KEY into the name field. Then paste your effx API key into the value field. You can retrieve your API key from within effx by navigating to Account Settings.

4. Click Add Secret, and let’s move on to the next step 👇

---
name: effx-cli-ci
on: push
jobs:
  lint-all:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: effxhq/effx-lint-action@v1
        with:
          directory: ${GITHUB_WORKSPACE}
  sync-all:
    runs-on: ubuntu-latest
    needs: lint-all
    if: github.ref == 'refs/heads/master'
    steps:
      - uses: actions/checkout@v2
      - uses: effxhq/effx-sync-action@v1
        with:
          directory: ${GITHUB_WORKSPACE}
        env:
          EFFX_API_KEY: ${{ secrets.EFFX_API_KEY }}

Set up Github Lint and Sync Workflow

By setting up this Github workflow, you can use both of effx’s Lint and Sync Actions

Lint Action -- parses and validates your effx components on every push to any branch. This action will fail if it discovers any effx.yaml file that has an invalid format, so that you can catch these issues before merging any code to your default branch.

Sync Action -- recursively discovers any file ending with effx.yaml and syncs it to the effx platform. On pushing to the default branch, this action will parse and save your effx components. In your .github/workflows/ directory, create a new file called effx-cli-ci.yaml and add the code to the right 👉

Note: if you use a default branch other than master, e.g. main, please update the config appropriately

Push effx-cli.yaml file to the default branch

To check to see if it's working properly, the workflow can then be found under the Actions tab of the repository

Now sit back and let the workflow automatically lint and sync your YAML files to effx. 💪

Using GitLab CI/CD Jobs

Automate syncing services to effx with Github Actions

We'll walk you through the workflow of validating and importing your services using GitLab's CI Job functionality which will help you reliably bring your effx.yaml files into effx.

Configure your Secret API key

You'll first need to configure a Variable within GitLab in order to use the CI/CD Job with effx.

1. Navigate to Settings > CI / CD for the repo

2. Jump to the section called Variables and choose Add Variable

3. On the Add variable screen, add EFFX_API_KEY as the Key and insert your effx API key into the Value field. You can find your API key in the effx platform by navigating to Account Settings. In addition, check both Protect Variable and Mask Variable options

1. Click Add variable and you're set!

image: ubuntu:latest

before_script:
  - curl -Lo effx https://effx.run/effx-cli/releases/latest/effx-cli_Linux_x86_64
  - sudo install effx /usr/local/bin

lint-all:
  stage: test
  script:
    - effx lint -d .

sync-all:
  stage: deploy
  variables:
    EFFX_API_KEY: ${EFFX_API_KEY}
  script:
    - effx sync -d .
  only:
    - master

Set up your .gitlab-ci.yml file

If you've made it this far, you're probably familiar with setting up a `.gitlab-ci.yml file. To the right is a recommendation if the file is empty, but feel free to adjust as you feel necessary.

Note: if you use a default branch other than master, e.g. main, please update the config appropriately

Push to your default branch

To complete the process, push the new .gitlab-ci.yml file to your main/master branch.

Now, whenever you merge code into the main branch for this repository, a job to lint and sync services to effx will run. This will find all effx.yaml files in the repo and lint and sync them accordingly.

You can view status by going to CI/CD > Jobs in the repository's navigation menu.

Using vcs-connect

vcs-connect is an open source project created by effx to help you easily import effx.yaml configurations across all of your repositories.

For more information on vcs-connect including how to set up and use it, visit its repository on Github at: https://github.com/effxhq/vcs-connect

Using CircleCI Orbs

# Lints all definitions on every commit
# Syncs all definitions on every commit to main
version: "2.1"
orbs:
  effx-cli: effx/effx-cli@1.0.0
workflows:
  effx-workflow:
    jobs:
      - effx-cli/lint-all:
          name: lint
      - effx-cli/sync-all:
          context: effx-api-credentials
          requires:
            - lint
          filter:
            branches:
              only: main

CircleCI provides shareable CI configurations through a feature called Orbs.

We regularly publish useful Jobs and Commands which can be found at https://circleci.com/developer/orbs/orb/effx/effx-cli.

An example workflow has been provided for your reference. The workflow demonstrates a common GitOps workflow, where only commits to the main branch are uploaded to effx.

CLI Documentation

Effx provides a command line tool that facilates validation and synchronization of Effx resources in your development environment. The CLI is the foundational tool in our git-based integrations.

Installation

# For Mac and Linux:
curl -Lo effx ${EFFX_BINARY_URL} && \
sudo install effx /usr/local/bin/

The latest stable binary can be found here:

Download the binary and add it to your PATH.

Working with the Effx CLI

# Lint all files in this directory (recursive)
effx lint -d .
# Lint a single file
effx lint -f effx.yaml

# Sync all files in this directory (recursive)
effx sync -d . -k ${EFFX_API_KEY}
# Sync a single file
effx sync -f effx.yaml -k ${EFFX_API_KEY}

File Naming

You must name your files either effx.yaml or to match the *.effx.yaml pattern. Both .yaml and .yml file extensions are supported.

API Documentation

effx provides a simple and powerful REST API to update services with your existing applications or infrastructure.

This API reference provides information on available endpoints and how to interact with them. Some example use cases of our API could be:

• updating service information from an existing internal system or deploy tool
• updating team information automatically from an internal directory

Getting started with our API

Before you can start using our APIs, you'll need your account's API key.

Log in to your account to https://app.effx.com with your credentials, navigate to your Account Settings page to retrieve your API key or just click here: https://app.effx.com/account_settings

New to effx and need an account? Visit https://effx.com to learn more and sign up!

Client Libraries / SDKs

Currently we have support for interacting with our API simply via any REST-enabled client. We've included examples on this site that use curl as the primary client mechanism. We're in the process of building clients in:

Go Node.js Ruby

Let us know at support@effx.com if you want (or are interested in writing) a library for a language not represented here.

Authentication

To authorize, use this code:

# With curl, you can just pass the correct header with each request
curl "https://api.effx.io/v2" \
  -H "X-Effx-Api-Key: YOUR_API_KEY" \
  -H 'Content-type: application/json'

Make sure to replace YOUR_API_KEY with your API key.

The effx API expects for the API key to be included in all API requests to the server via an HTTP Header. Provide your API key as the value for X-Effx-Api-Key.

Services

{
  "version": "effx/v1",
  "kind": "service",
  "spec": {
    "name": "the canonical name of the service",
    "description": "something to describe what this service does",
    "contact": {
      "email": "engineering@effx.com",
      "onCall": {
        "label": "how to label the link",
        "url": "https://app.effx.com"
      },
      "chat": {
        "label": "how to label the link",
        "url": "https://app.effx.com"
      },
      "issueTracker": {
        "label": "how to label the link",
        "url": "https://app.effx.com"
      }
    },
    "linkGroups": [
      {
        "label": "Dashboards",
        "links": [
          {
            "label": "datadog",
            "url": "https://datadoghq.com/some/link"
          },
          {
            "label": "newrelic",
            "url": "https://newrelic.com/appid/dashboard"
          }
        ]
      }
    ],
    "tags": {
      "go": "1.13.5",
      "tier": "0",
      "group": "auth"
    },
    "annotations": {
      "effx.io/owned-by": "authentication team"
    }
  }
}

Create or update a service

This endpoint receives a PUT request with a JSON body and returns a success or error

Errors