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 displayeddescription
- The description is a string describing what the service does -- engineers will be able to discover the service by searching for terms in the descriptionannotations
- 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 aregroup
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 of1.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 serviceonCall
- link to the on-call rotation for the servicechat
- link to the best chat room to discuss issues with the serviceissueTracker
- 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 servicedocumentation
- where is the service's documentation or APIrunbooks
- 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 perlinkGroup
, each requiring alabel
andurl
. Thelabel
appears on the button for the link within the user interface. You can also use the YAML Wizard to generate youreffx.yaml
, modify the values in theexample-service
or hand craft your own YAML if you're comfortable.
dependencies
- Define dependencies on other servicesmanual
- A section for explicit declarations (array). Each dependency has akind
of entity to depend on (defaults to "service") & aname
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 displayeddescription
- The description is a string describing what the team doesannotations
- 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 aregroup
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 of1.15.5
like in the example.contact
- Provide contact information for a particular service. Available contact types are:email
- email address for the teamonCall
- link to the on-call rotation for the teamchat
- link to the best chat room to contact the teamissueTracker
- 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.
Navigate to the repository's Settings in the Github web interface
Select Secrets from the left side menu, and create a New Secret
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.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.
Navigate to Settings > CI / CD for the repo
Jump to the section called Variables and choose Add Variable
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
- 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:
- 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
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. |