• This repository has been archived on 12/Jul/2023
  • Stars
    star
    267
  • Rank 147,696 (Top 4 %)
  • Language
    Java
  • License
    Apache License 2.0
  • Created over 7 years ago
  • Updated 9 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

"The path to execution", Styx is a service that schedules batch data processing jobs in Docker containers on Kubernetes.

This repo was archived!

We decided to discontinue the Styx oss repo.

Styx

CircleCI Coverage Status License Maven Central

A batch job scheduler for Kubernetes

Description

Styx is a service that is used to trigger periodic invocations of Docker containers. The information needed to schedule such invocations, is read from a set of files on disk or an external service providing such information. The service takes responsibility for triggering and possibly also re-triggering invocations until a successful exit status has been emitted or some other limit has been reached. Styx is built using the Apollo framework and uses Kubernetes for container orchestration.

Styx can optionally provide some dynamic arguments to container executions that indicates which time period a particular invocation belongs to. For example an hourly job for the first hour of 2016-01-01 might have the dynamic argument 2016-01-01T00 appended to the container invocation.

The envisioned main use case for Styx is to execute data processing job, possibly long running processes that transform data periodically. Its initial use case is to run workflows of jobs orchestrated using Luigi, but it does not have any intrinsic ties to Luigi. Styx can just as well execute a container with some simple bash scripts.

Styx was built to function smoothly on Google Cloud Platform, thus it makes use of Google products such as Google Cloud Datastore, Google Cloud Bigtable and Google Container Engine. However, the integrations with these products are all done through clear interfaces and other backends can easily be added.

Key concepts

The key concept that Styx concerns itself with is Workflows. A Workflow is either enabled or disabled and has a Schedule. A Schedule specifies how often a Workflow should be triggered, which Docker image to run and which arguments to pass to it on each execution. Each time a Workflow is triggered, a Workflow Instance is created. The Workflow instance is tracked as 'active' until at least one execution of the Docker image returns with a 0 exit code. Styx keeps track of Workflow Instance executions and provides information about them via the API.

Development status

Styx is actively being developed and deployed internally at Spotify where it is being used to run more than 10000 production workflows. Because of how we build and integrate infrastructure components at Spotify, this repository does not contain a GUI at the time of writing, while we do have one internally. The goal is to break out more of these components into open source projects that complement each other.

More docs

Usage

Setup

A fully functional Service can be found in styx-standalone-service. This packaging contains both the API and Scheduler service in one artifact. This is how you build and run it.

The following configuration keys in styx-standalone.conf have to be specified for the service to work:

# Google Container Engine (GKE) cluster
styx.gke.default.project-id = ""
styx.gke.default.cluster-zone = ""
styx.gke.default.cluster-id = ""
styx.gke.default.namespace = ""

# Google Cloud Bigtable instance
styx.bigtable.project-id = ""
styx.bigtable.instance-id = ""

# Google Cloud Datastore config
styx.datastore.project-id = ""
styx.datastore.namespace = ""

Build the project:

> mvn package

Run the service:

> java -jar styx-standalone-service/target/styx-standalone-service.jar

Workflow configuration

Refer to API Specification for how to deploy a workflow.

id: my-workflow
docker_image: my-workflow:0.1
docker_args: ['./run.sh', '{}']
schedule: hourly
offset: PT1H
service_account: [email protected]
running_timeout: PT2H
retry_condition: "(#tries < 2 && #triggerType == 'backfill') || (#triggerType != 'backfill')"

id [string]

A unique identifier for the workflow (lower-case-hyphenated). This identifier is used to refer to the workflow through the API.

docker_image [string]:

The Docker image that should be executed.

docker_args [string]

The list of arguments passed to the Docker container.

This list should only contain strings. Any occurrences of the {} placeholder argument will be replaced with the current partition date or datehour. Note that it must be quoted in the yaml file in order not to be interpreted as an object.

Example arguments for the supported schedule values:

- hourly - 2016-04-01T14, 2016-04-01T15, ... (UTC hours)
- daily  - 2016-04-01,    2016-04-02,    ...
- weekly - 2016-04-04,    2016-04-11,    ... (Mondays)

schedule [string]

How often the workflow should be triggered and what the {} placeholder will be replaced with in docker_args.

Supports cron syntax, along with a set of human readable aliases:

@hourly,   hourly   = 0 * * * *
@daily,    daily    = 0 0 * * *
@weekly,   weekly   = 0 0 * * MON
@monthly,  monthly  = 0 0 1 * *
@yearly,   yearly   = 0 0 1 1 *
@annually, annually = 0 0 1 1 *

offset [string]

An ISO 8601 Duration specification for offsetting the cron schedule.

This is useful for when setting up a schedule that needs to be offset in time relative to the schedule timestamps. For instance, an hourly schedule that needs to process a bucket of data for each hour will not be able to run until at the end of that hour. We can then use an offset value of PT1H. The injected placeholder would reflect a logical time of the schedule (00, 01, 02, ...) one hour earlier than the actual run time (01, 02, 03, ...). This is specially useful for irregular schedules.

In fact, it is so common that we need to use a "last hour" parameter in jobs that we've set the default offset for all the well known (aliased) schedules to +1 period. E.g for an @hourly schedule, the default offset is PT1H, and for a @daily schedule the offset is P1D

Example: a job needs to run daily at 2 AM but the partition argument needs to be midnight

schedule: '@daily'
offset: P1DT2H

At 2017-06-30T02 the execution for 2017-06-29 will be triggered.

service_account [email address]

The Service Account email address belonging to a project in Google Cloud Platform.

If the workflow intends to use keys of a Service Account, Styx will create both JSON and p12 keys for the specified service_account, rotate keys on daily basis, and garbage collect unused keys older than 48h.

Styx stores the created keys in Kubernetes Secrets and mounts them under /etc/styx-wf-sa-keys/ in the container.

Styx injects an environment variable to the container named as GOOGLE_APPLICATION_CREDENTIALS pointing to the JSON key file.

In order for Styx to be able to create/delete keys for the service_account of a workflow, the Service Account that Styx itself runs as should be granted Service Account Key Admin role for the service_account of the workflow.

If authorization is enabled for the service, the service_account will be used to authorize deployments and actions (create/modify/delete, trigger a new instance, retry/halt an existing instance and create backfill) on the workflow. To authorize an account, grant it the configured role) for the Service Account of the workflow.

For information on how to grant an account a role in a Service Account, follow this guide: Granting Roles to Service Accounts.

env [dictionary]

Custom environment variables to be injected into running container.

running_timeout [string]

An ISO 8601 Duration specification for timing out container execution. The default is configurable in styx conf file through styx.stale-state-ttls.running. If not set it defaults to styx.stale-state-ttls.default. The upper boundary of the running_timeout is configurable through styx.max-running-timeout. If not set it defaults to styx.stale-state-ttls.running, which defaults to styx.stale-state-ttls.default as stated above.

retry_condition [string]

A SpEL boolean expression. If the expression evaluates to false, Styx will stop retrying and halt the workflow instance immediately. This configuration has no impact on possible max number of tries, meaning it can only be used to halt workflow instance earlier.

The following variables will be injected by Styx so that they can be used in the expression:

  • #exitCode: the exit code from the last execution
  • #tries: total number of tries, which equals to 1 when the first time a workflow instance gets executed and 2 when the first retry is issued
  • #consecutiveFailures: total number of consecutive failures that is not missing dependency
  • #triggerType: natural, backfill or ad-hoc

Triggering and executions

Each time a Workflow Schedule is triggered, Styx will treat that trigger as a first class entity. Each Trigger will have at least one Execution which can potentially take a long time to execute. If another Trigger happens during this time, both triggers will be active, each with one running container. Because Styx treats each Trigger individually, it can ensure that each one of them complete successfully.

Styx does not assume anything about what is executed in the container, it only cares about the exit code. Any execution returning a non-zero exit code will either cause a re-try to be scheduled, or be interpreted as a permanent failure of the workflow instance. For detailed description of exit codes, please refer to Workflow state graph section in Styx design.

Injected environment variables

For each execution, Styx will inject a set of environment variables into the Docker container.

Variable Name Description
STYX_COMPONENT_ID The component id of the workflow. This will be the filename of the file which defines the workflow schedule.
STYX_WORKFLOW_ID The workflow id of the workflow. This is the id field specified in the workflow schedule.
STYX_PARAMETER The parameter argument. See section about docker_args above.
STYX_SERVICE_ACCOUNT The service account.
STYX_COMMIT_SHA The commit-sha of the workflow.
STYX_DOCKER_ARGS The arguments passed to the container.
STYX_DOCKER_IMAGE The docker image.
STYX_TRIGGER_ID The ID of the trigger.
STYX_TRIGGER_TYPE The type of the trigger. Possible values are: natural, adhoc, backfill and unknown
STYX_EXECUTION_ID A unique identifier for the execution. This is the execution id used to identify execution attempts of a trigger.
STYX_LOGGING Container logging format, text or structured.
STYX_ENVIRONMENT Styx environment, staging, production, testing, etc. Should be defined in styx-standalone.conf.
STYX_EXECUTION_COUNTER to be implemented - A counter indicating which execution this is. Goes from 0..N per trigger.

High availability

Since version 2.0, Styx supports full HA (High Availability) where both styx-api-service and styx-scheduler-service can be set up to have multiple instances.

Authorization

Enabling authorization means that any workflow with a configured service_account will only allow authorized users to deploy and manage it.

You can enable authorization in your configuration, either for all workflows or a subset of workflows. You will also need to provide the name of the role to use for determining if an account is an authorized user of the service_account or not. Read more about how to authorize accounts for a service account here.

Development

Backwards Compatibility & API Stability

Most core features and Styx APIs are considered to be stable and changes to them should be backwards compatible. Styx users should normally not be affected by minor/patch releases.

Stable features and APIs:

  • Styx CLI
  • Styx REST API
  • Styx Client API
  • Styx Workflows

All other APIs are considered unstable and can change at any time. E.g. the StyxScheduler class offers some plugin APIs for customizing functionality but they might change at any time. This should only affect engineers that link against and customize the Styx services.

Code Coverage

An aggregate code coverage report for the entire project is created by the styx-report submodule.

> mvn clean verify
> open styx-report/target/site/jacoco-aggregate/index.html

CircleCI builds submit code coverage reports to codecov.io. In addition, the aggregate JaCoCo report can be viewed under the Artifacts tab in the CircleCI build view.


This project adheres to the Open Code of Conduct. By participating, you are expected to honor this code.

More Repositories

1

luigi

Luigi is a Python module that helps you build complex pipelines of batch jobs. It handles dependency resolution, workflow management, visualization etc. It also comes with Hadoop support built in.
Python
17,089
star
2

annoy

Approximate Nearest Neighbors in C++/Python optimized for memory usage and loading/saving to disk
C++
12,458
star
3

docker-gc

INACTIVE: Docker garbage collection of containers and images
Shell
5,068
star
4

pedalboard

🎛 🔊 A Python library for audio.
C++
4,823
star
5

chartify

Python library that makes it easy for data scientists to create charts.
Python
3,447
star
6

basic-pitch

A lightweight yet powerful audio-to-MIDI converter with pitch bend detection
Python
2,818
star
7

dockerfile-maven

MATURE: A set of Maven tools for dealing with Dockerfiles
Java
2,730
star
8

docker-maven-plugin

INACTIVE: A maven plugin for Docker
Java
2,652
star
9

scio

A Scala API for Apache Beam and Google Cloud Dataflow.
Scala
2,485
star
10

helios

Docker container orchestration platform
Java
2,097
star
11

web-api-examples

Basic examples to authenticate and fetch data using the Spotify Web API
HTML
1,889
star
12

HubFramework

DEPRECATED – Spotify’s component-driven UI framework for iOS
Objective-C
1,864
star
13

apollo

Java libraries for writing composable microservices
Java
1,648
star
14

dh-virtualenv

Python virtualenvs in Debian packages
Python
1,590
star
15

docker-client

INACTIVE: A simple docker client for the JVM
Java
1,425
star
16

docker-kafka

Kafka (and Zookeeper) in Docker
Shell
1,400
star
17

SPTPersistentCache

Everyone tries to implement a cache at some point in their iOS app’s lifecycle, and this is ours.
Objective-C
1,244
star
18

mobius

A functional reactive framework for managing state evolution and side-effects.
Java
1,205
star
19

sparkey

Simple constant key/value storage library, for read-heavy systems with infrequent large bulk inserts.
C
1,143
star
20

ruler

Gradle plugin which helps you analyze the size of your Android apps.
Kotlin
1,100
star
21

voyager

🛰️ Voyager is an approximate nearest-neighbor search library for Python and Java with a focus on ease of use, simplicity, and deployability.
C++
1,090
star
22

XCMetrics

XCMetrics is the easiest way to collect Xcode build metrics and improve developer productivity.
Swift
1,079
star
23

web-api

This issue tracker is no longer used. Join us in the Spotify for Developers forum for support with the Spotify Web API ➡️ https://community.spotify.com/t5/Spotify-for-Developers/bd-p/Spotify_Developer
RAML
981
star
24

echoprint-codegen

Codegen for Echoprint
C++
948
star
25

snakebite

A pure python HDFS client
Python
859
star
26

heroic

The Heroic Time Series Database
Java
843
star
27

klio

Smarter data pipelines for audio.
Python
827
star
28

XCRemoteCache

Swift
815
star
29

apps-tutorial

A Spotify App that contains working examples of the use of Spotify Apps API
627
star
30

SPTDataLoader

The HTTP library used by the Spotify iOS client
Objective-C
624
star
31

ios-sdk

Spotify SDK for iOS
Objective-C
609
star
32

postgresql-metrics

Tool that extracts and provides metrics on your PostgreSQL database
Python
584
star
33

JniHelpers

Tools for writing great JNI code
C++
584
star
34

reactochart

📈 React chart component library 📉
JavaScript
548
star
35

Mobius.swift

A functional reactive framework for managing state evolution and side-effects [Swift implementation]
Swift
543
star
36

dockerfile-mode

An emacs mode for handling Dockerfiles
Emacs Lisp
520
star
37

threaddump-analyzer

A JVM threaddump analyzer
JavaScript
482
star
38

featran

A Scala feature transformation library for data science and machine learning
Scala
467
star
39

android-sdk

Spotify SDK for Android
HTML
440
star
40

echoprint-server

Server for the Echoprint audio fingerprint system
Java
398
star
41

web-scripts

DEPRECATED: A collection of base configs and CLI wrappers used to speed up development @ Spotify.
TypeScript
381
star
42

completable-futures

Utilities for working with futures in Java 8
Java
378
star
43

SpotifyLogin

Swift framework for authenticating with the Spotify API
Swift
344
star
44

ratatool

A tool for data sampling, data generation, and data diffing
Scala
334
star
45

fmt-maven-plugin

Opinionated Maven Plugin that formats your Java code.
Java
299
star
46

big-data-rosetta-code

Code snippets for solving common big data problems in various platforms. Inspired by Rosetta Code
Scala
286
star
47

trickle

A small library for composing asynchronous code
Java
284
star
48

coordinator

A visual interface for turning an SVG into XY coördinates.
HTML
282
star
49

pythonflow

🐍 Dataflow programming for python.
Python
279
star
50

cstar

Apache Cassandra cluster orchestration tool for the command line
Python
254
star
51

netty-zmtp

A Netty implementation of ZMTP, the ZeroMQ Message Transport Protocol.
Java
242
star
52

ios-style

Guidelines for iOS development in use at Spotify
240
star
53

cassandra-reaper

Software to run automated repairs of cassandra
235
star
54

confidence

Python
232
star
55

spotify-web-api-ts-sdk

A Typescript SDK for the Spotify Web API with types for returned data.
TypeScript
231
star
56

docker-cassandra

Cassandra in Docker with fast startup
Shell
219
star
57

terraform-gke-kubeflow-cluster

Terraform module for creating GKE clusters to run Kubeflow
HCL
209
star
58

dns-java

DNS wrapper library that provides SRV lookup functionality
Java
203
star
59

linux

Spotify's Linux kernel for Debian-based systems
C
203
star
60

git-test

test your commits
Shell
202
star
61

SPStackedNav

[DEPRECATED] Navigation controller which represents its content in stacks of panes, rather than one at a time
Objective-C
195
star
62

basic-pitch-ts

A lightweight yet powerful audio-to-MIDI converter with pitch bend detection.
TypeScript
194
star
63

quickstart

A CommonJS module resolver, loader and compiler for node.js and browsers.
JavaScript
193
star
64

spotify-json

Fast and nice to use C++ JSON library.
C++
190
star
65

dbeam

DBeam exports SQL tables into Avro files using JDBC and Apache Beam
Java
181
star
66

flink-on-k8s-operator

Kubernetes operator for managing the lifecycle of Apache Flink and Beam applications.
Go
178
star
67

bazel-tools

Tools for dealing with very large Bazel-managed repositories
Java
165
star
68

lingon

A user friendly tool for building single-page JavaScript applications
JavaScript
162
star
69

dataenum

Algebraic data types in Java.
Java
159
star
70

magnolify

A collection of Magnolia add-on modules
Scala
157
star
71

async-google-pubsub-client

[SUNSET] Async Google Pubsub Client
Java
156
star
72

gcp-audit

A tool for auditing security properties of GCP projects.
Python
156
star
73

spark-bigquery

Google BigQuery support for Spark, SQL, and DataFrames
Scala
154
star
74

flo

A lightweight workflow definition library
Java
146
star
75

folsom

An asynchronous memcache client for Java
Java
143
star
76

should-up

Remove most of the "should" noise from your tests
JavaScript
143
star
77

missinglink

Build time tool for detecting link problems in java projects
Java
142
star
78

zoltar

Common library for serving TensorFlow, XGBoost and scikit-learn models in production.
Java
141
star
79

android-auth

Spotify authentication and authorization for Android. Part of the Spotify Android SDK.
HTML
139
star
80

proto-registry

An implementation of the Protobuf Registry API
TypeScript
139
star
81

futures-extra

Java library for working with Guava futures
Java
136
star
82

annoy-java

Approximate nearest neighbors in Java
Java
134
star
83

spydra

Ephemeral Hadoop clusters using Google Compute Platform
Java
133
star
84

spotify-tensorflow

Provides Spotify-specific TensorFlow helpers
Python
124
star
85

docker-stress

Simple docker stress test and monitoring tools
Python
124
star
86

spotify-web-playback-sdk-example

React based example app that creates a new player in Spotify Connect to play music from in the browse using Spotify Web Playback SDK.
JavaScript
120
star
87

crtauth

a public key backed client/server authentication system
Python
118
star
88

redux-location-state

Utilities for reading & writing Redux store state to & from the URL
JavaScript
118
star
89

sparkey-java

Java implementation of the Sparkey key value store
Java
117
star
90

rspec-dns

Easily test your DNS with RSpec
Ruby
108
star
91

web-playback-sdk

This issue tracker is no longer used. Join us in the Spotify for Developers forum for support with the Spotify Web Playback SDK ➡️ https://community.spotify.com/t5/Spotify-for-Developers/bd-p/Spotify_Developer
108
star
92

ffwd-ruby

An event and metrics fast-forwarding agent.
Ruby
106
star
93

realbook

Easier audio-based machine learning with TensorFlow.
Python
106
star
94

github-java-client

A Java client to Github API
Java
105
star
95

gimme

Creating time bound IAM Conditions with ease and flair
Python
103
star
96

super-smash-brogp

Sends and withdraws BGP prefixes for fun.
Python
98
star
97

lighthouse-audit-service

TypeScript
93
star
98

noether

Scala Aggregators used for ML Model metrics monitoring
Scala
91
star
99

python-graphwalker

Python re-implementation of the graphwalker testing tool
Python
90
star
100

spotify-js-challenge

JavaScript
87
star