NAV
yaml shell json

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:

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:

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 repo settings

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

  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. repo 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

repo settings

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

repo settings

  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:

OS Location
Linux (64-bit) https://effx.run/effx-cli/releases/latest/effx-cli_Linux_x86_64
Linux (32-bit) https://effx.run/effx-cli/releases/latest/effx-cli_Linux_i386
MacOS (Darwin) https://effx.run/effx-cli/releases/latest/effx-cli_Darwin_x86_64
Windows (64-bit) https://effx.run/effx-cli/releases/latest/effx-cli_Windows_x86_64.exe
Windows (32-bit) https://effx.run/effx-cli/releases/latest/effx-cli_Windows_i386.exe

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}
Overview
effx lint - Validates YAML syntax
effx sync - Uploads YAML to your Effx account (API Key required)

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:

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

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The kitten requested is hidden for administrators only.