APIの管理

パッケージ

他のサービスのように、APIは8080番ポートをexposeしたDockerイメージを提供しています。

$ docker run -d -p 9000:8080 screwdrivercd/screwdriver:stable
$ open http://localhost:9000

このDockerイメージはそのバージョン(例: 1.2.3)や動的なlateststableでタグ付けされています。特に理由がなければstableまたは固定のバージョンタグを利用してください。

設定

Screwdriverは最初から多くのデフォルト設定がされていますが、config/local.yaml や環境変数を使うことでデフォルト設定を上書きできます。設定できる全ての環境変数はこちらに定義されています。

認証 / 認可

誰がAPIにアクセスでき、何ができるかを設定します。

キー 必須 説明
JWT_ENVIRONMENT いいえ JWT を生成する環境です。例えば prodbeta などを指定します。JWT に環境変数を含めたくないのであれば、この環境変数は設定しないでください。(''のような設定もしないでください)
SECRET_JWT_PRIVATE_KEY はい JWTに署名するための秘密鍵です。次のコマンドにより生成できます。$ openssl genrsa -out jwt.pem 2048
SECRET_JWT_PUBLIC_KEY はい 署名を検証するための公開鍵です。次のコマンドにより生成できます。$ openssl rsa -in jwt.pem -pubout -out jwt.pub
SECRET_JWT_QUEUE_SVC_PUBLIC_KEY はい プラグインがキューの場合に署名を検証するための公開鍵です。次のコマンドにより生成できます。 $ openssl rsa -in jwtqs.pem -pubout -out jwtqs.pub
SECRET_COOKIE_PASSWORD はい セッションデータを暗号化するためのパスワードです。32文字以上である必要があります。
SECRET_PASSWORD はい SECRETを暗号化するためのパスワードです。32文字以上である必要があります。
IS_HTTPS いいえ サーバーがhttpsで動作しているかどうかを設定するフラグです。OAuthフローのフラグとして利用されます。(デフォルトはfalseです)
SECRET_WHITELIST いいえ システムに対して認証できるユーザのホワイトリストです。空の場合は全ユーザを許可します。(JSONの配列形式)
SECRET_ADMINS いいえ システムに対して認証できるユーザのホワイトリストです。空の場合は全ユーザを許可します。(JSONの配列形式)
# config/local.yaml
auth:
    jwtPrivateKey: |
        PRIVATE KEY HERE
    jwtPublicKey: |
        PUBLIC KEY HERE
    jwtQueueServicePublicKey: |
        QUEUE SVC PUBLIC KEY HERE
    cookiePassword: 975452d6554228b581bf34197bcb4e0a08622e24
    encryptionPassword: 5c6d9edc3a951cda763f650235cfc41a3fc23fe8
    https: false
    whitelist:
        - github:batman
        - github:robin
    admins:
        - github:batman

マルチビルドクラスター

デフォルトでは、build cluster機能はオフになっています。

キー デフォルト 説明
MULTI_BUILD_CLUSTER_ENABLED false ビルドクラスターがオンかオフか。 オプション: true または false
# config/local.yaml
multiBuildCluster:
    enabled: true

ビルド変数

環境変数

クラスタ内の全てのビルドに対して環境変数を事前設定できます。デフォルトでは{ SD_VERSION: 4 }が設定されています。

キー デフォルト 説明
CLUSTER_ENVIRONMENT_VARIABLES { SD_VERSION: 4 } ビルドのデフォルト環境変数です。例: { SD_VERSION: 4, SCM_CLONE_TYPE: "ssh" }

リモートジョイン

デフォルトでは、リモートジョイン機能は無効になっています。

キー デフォルト 説明
EXTERNAL_JOIN false リモートジョイン機能が有効か無効か。 設定値: true または false
# config/local.yaml
build:
    environment: CLUSTER-ENV-IN-JSON-FORMAT
    externalJoin: true

ブックエンドプラグイン

ビルド中に使用されるブックエンドプラグインを設定できます。ブックエンドプラグインは、各クラスター毎に設定することができます。
デフォルトではscmが有効になっており、SCMのcheckoutコマンドでビルドを開始します。

もしご自身で開発したブックエンドを使用したい場合はこちらをご覧ください。

キー デフォルト 説明
BOOKENDS None 各ビルドの最初と最後に実行されるブックエンドの連想配列です。以下の書式で記述します。{"default": {"setup": ["scm", ...], "teardown": [...]}, "clusterA": {"setup": ["scm", ...], "teardown": [...]}}
# config/local.yaml
bookends:
  default: 
    setup:
      - scm
      - my-custom-bookend
    teardown:
      - screwdriver-artifact-bookend
      - screwdriver-cache-bookend
  clusterA:
    setup: ...
    teardown: ...
  clusterB:
    setup: ...
    teardown: ...

clusterAclusterBには、クラスター管理者が用意したビルドクラスターを指定してください。詳細についてはこちらをご確認ください。
bookendsで設定されたクラスタ以外に割り当てられた場合、defaultに設定されたブックエンドプラグインが使用されます。

カバレッジ bookend

現在のところ、SonarQube をカバレッジ bookend としてサポートしています。

Sonar

クラスタ内で Sonar を使用するには、Sonar サーバをセットアップする必要があります(sonar パイプラインに例があります)。その後、次の環境変数を設定します。

キー 必須 説明
COVERAGE_PLUGIN はい sonar としてください
COVERAGE_PLUGIN_DEFAULT_ENABLED いいえ coverage-bookend がカバレッジスキャンをデフォルトで実行するかどうか。 デフォルト true
URI はい Screwdriver の API の URI
ECOSYSTEM_UI はい Screwdriver の UI の URL
COVERAGE_SONAR_HOST はい Sonar の host の URL
COVERAGE_SONAR_ADMIN_TOKEN はい Sonar の admin token
COVERAGE_SONAR_ENTERPRISE いいえ SonarQube を Enterprise 版で利用している(true)か、OpenSourceEdition で利用している(false)か。デフォルト値は false
COVERAGE_SONAR_GIT_APP_NAME いいえ SonarのPull Request DecorationのためのGithub app名。デフォルト値は Screwdriver Sonar PR Checks です。この機能にはSonar Enterprise Editionが必要です。詳細はSonarのドキュメントをご覧ください。

更に screwdriver-artifact-bookend に加えて、screwdriver-coverage-bookendBOOKENDS の環境変数に JSON フォーマットで teardown bookend として設定する必要があります。詳しくは、上の Bookend Plugins の節を見てください。SonarQube の Enterprise 版を利用している場合には、 SonarQube のプロジェクトキーや名前はデフォルトでは パイプライン スコープになります。これにより、 PR 解析が使えるようになったり、 Screwdriver のジョブ毎に個別のプロジェクトが作成されることを防げます。Enterprise 版の SonarQube を使用していない場合、SonarQube のプロジェクトキーや名前はデフォルトでは ジョブ スコープになります。

配信

サービスがどのようにトラフィックを受け付けるかを設定します。

キー デフォルト 説明
PORT 80 listenするポート
HOST 0.0.0.0 listenするホスト(そのマシン上からの接続だけを受け付けるときだけlocalhostに設定)
URI http://localhost:80 外部から接続可能なURI (通常はロードバランサーやCNAME)
HTTPD_TLS false SSLサポートの有無です。有効にする場合はfalsetls.createServerに渡すJSONオブジェクトに置き換えてください。
# config/local.yaml
httpd:
    port: 443
    host: 0.0.0.0
    uri: https://localhost
    tls:
        key: |
            PRIVATE KEY HERE
        cert: |
            YOUR CERT HERE

エコシステム

外部からアクセス可能なUI、アーティファクトストアのURLを指定します。

キー デフォルト 説明
ECOSYSTEM_UI https://cd.screwdriver.cd ユーザーインターフェースのURL
ECOSYSTEM_STORE https://store.screwdriver.cd アーティファクトストアURL
ECOSYSTEM_QUEUE http://sdqueuesvc.screwdriver.svc.cluster.local キュープラグインで使用されるキューサービスの内部URL
# config/local.yaml
ecosystem:
    # 外部からルーティング可能なUI用URL
    ui: https://cd.screwdriver.cd
    # 外部からルーティング可能なArtifact Store用URL
    store: https://store.screwdriver.cd
    # 内部でルーティング可能な、キューsvcのFQDNS
    queue: http://sdqueuesvc.screwdriver.svc.cluster.local

データストアプラグイン

Postgres, MySQL, や Sqlite を使用するにはsequelizeプラグインを使用します。

Sequelize

下記の環境変数を設定します。

環境変数名 必須 デフォルト値 説明
DATASTORE_PLUGIN はい   sequelizeを指定
DATASTORE_SEQUELIZE_DIALECT いいえ mysql sqlite, postgres, mysql, または mssql が指定可能
DATASTORE_SEQUELIZE_DATABASE いいえ screwdriver データベース名
DATASTORE_SEQUELIZE_USERNAME sqliteでは不要   ログインユーザー名
DATASTORE_SEQUELIZE_PASSWORD sqliteでは不要   ログインパスワード
DATASTORE_SEQUELIZE_STORAGE sqliteのみ必要   sqliteのストレージの場所
DATASTORE_SEQUELIZE_HOST いいえ   ネットワークホスト
DATASTORE_SEQUELIZE_PORT いいえ   ネットワークホスト
DATASTORE_SEQUELIZE_RO いいえ   host, port, database, username, passwordなどを含むJSON形式の値
Metricsエンドポイントのみで使うRead Onlyデータストアインスタンス情報です
# config/local.yaml
datastore:
    plugin: sequelize
    sequelize:
        dialect: TYPE-OF-SERVER
        storage: STORAGE-LOCATION
        database: DATABASE-NAME
        username: DATABASE-USERNAME
        password: DATABASE-PASSWORD
        host: NETWORK-HOST
        port: NETWORK-PORT
        readOnly: DATASTORE-READONLY-INSTANCE

Executorプラグイン

現在はkubernetesdockerVMs in KubernetesnomadJenkinsqueue executor をサポートしています。 詳しくは custom-environment-variables をご覧ください。

Kubernetes (k8s)

下記の環境変数を設定します。

環境変数名 デフォルト値 説明
EXECUTOR_PLUGIN k8s デフォルトの Executor (例: k8s, docker, k8s-vm, nomad, jenkins or queue)
LAUNCH_VERSION stable 使用する Launcher のバージョン
EXECUTOR_PREFIX なし Pod 名につけられる prefix
EXECUTOR_K8S_ENABLED true Kubernetes executor を利用可能にするフラグ
K8S_HOST kubernetes.default Kubernetes のホスト
K8S_TOKEN デフォルトでは /var/run/secrets/kubernetes.io/serviceaccount/token から読まれます Kubernetes のリクエストを認証するためのJWT
K8S_JOBS_NAMESPACE default Kubernetes ジョブ用ネームスペース
K8S_CPU_MICRO 0.5 micro 時の CPU のコア数
K8S_CPU_LOW 2 low 時の CPU のコア数
K8S_CPU_HIGH 6 high 時の CPU のコア数
K8S_CPU_TURBO 12 turbo 時の CPU のコア数
K8S_MEMORY_MICRO 1 micro 時のメモリ数(GB)
K8S_MEMORY_LOW 2 low 時のメモリ数(GB)
K8S_MEMORY_HIGH 12 high 時のメモリ数(GB)
K8S_MEMORY_TURBO 16 turbo 時のメモリ数(GB)
K8S_BUILD_TIMEOUT 90 クラスタ内の全てのビルドのデフォルトのタイムアウト時間(分)
K8S_MAX_BUILD_TIMEOUT 120 クラスタ内の全てのビルドでユーザが設定可能な最大のタイムアウト時間(分)
K8S_NODE_SELECTORS {} pod のスケジューリング用の k8s の node selector (フォーマット { label: 'value' }) https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#step-one-attach-label-to-the-node
K8S_PREFERRED_NODE_SELECTORS {} pod のスケジューリング用の k8s の node selector (フォーマット { label: 'value' }) https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#node-affinity-beta-feature
K8S_POD_DNS_POLICY ClusterFirst ビルドポッドのDNSポリシー https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-s-dns-policy
K8S_POD_IMAGE_PULL_POLICY Always ビルドポッドイメージのPullポリシー https://kubernetes.io/docs/concepts/containers/images/#updating-images
K8S_POD_LABELS { app: 'screwdriver', tier: 'builds', sdbuild: buildContainerName } クラスタ設定のための k8s ポッドラベル (例: { network-egress: ‘restricted’ } とすると、デフォルトでパブリックなインターネットへのアクセスをブロックしてビルドを実行します。)
K8S_IMAGE_PULL_SECRET_NAME ’’ K8sのimagePullSecrets名 (オプション) https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#create-a-pod-that-uses-your-secret
DOCKER_FEATURE_ENABLED false ビルドポッド内でDocker In Dockerを有効にするフラグ
K8S_RUNTIME_CLASS ’’ ランタイムクラス
TERMINATION_GRACE_PERIOD_SECONDS 60 ビルドポッドが削除されるまでの猶予時間
# config/local.yaml
executor:
    plugin: k8s
    k8s:
        options:
            kubernetes:
                # kubernetes クラスタのホストかIP
                host: YOUR-KUBERNETES-HOST
                token: JWT-FOR-AUTHENTICATING-KUBERNETES-REQUEST
                jobsNamespace: default
            launchVersion: stable

VMs in Kubernetes (k8s-vm)

k8s-vm executor を使用している場合には、ビルドは Kubernetes 上の Pod 内の VM で実行されます。

環境変数名 デフォルト値 説明
EXECUTOR_PLUGIN k8s デフォルトの executor (k8s-vm を設定してください)
LAUNCH_VERSION stable 使用する Launcher のバージョン
EXECUTOR_PREFIX なし Pod 名につけられる prefix
EXECUTOR_K8SVM_ENABLED true Kubernetes VM executor を利用可能にするフラグ
K8S_HOST kubernetes.default Kubernetes のホスト
K8S_TOKEN デフォルトでは /var/run/secrets/kubernetes.io/serviceaccount/token から読まれます Kubernetes のリクエストを認証するためのJWT
K8S_JOBS_NAMESPACE default Kubernetes ジョブ用ネームスペース
K8S_BASE_IMAGE なし Kubernetes VM のベースイメージ
K8S_CPU_MICRO 1 micro 時の CPU のコア数
K8S_CPU_LOW 2 low 時の CPU のコア数
K8S_CPU_HIGH 6 high 時の CPU のコア数
K8S_CPU_TURBO 12 turbo 時の CPU のコア数
K8S_MEMORY_MICRO 1 micro 時のメモリ数(GB)
K8S_MEMORY_LOW 2 low 時のメモリ数(GB)
K8S_MEMORY_HIGH 12 high 時のメモリ数(GB)
K8S_MEMORY_TURBO 16 turbo 時のメモリ数(GB)
K8S_VM_BUILD_TIMEOUT 90 クラスタ内の全てのビルドのデフォルトのタイムアウト時間(分)
K8S_VM_MAX_BUILD_TIMEOUT 120 クラスタ内の全てのビルドでユーザが設定可能な最大のタイムアウト時間(分)
K8S_VM_NODE_SELECTORS {} pod のスケジューリング用の k8s の node selector (フォーマット { label: 'value' }) https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#step-one-attach-label-to-the-node
K8S_VM_PREFERRED_NODE_SELECTORS {} pod のスケジューリング用の k8s の node selector (フォーマット { label: 'value' }) https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#node-affinity-beta-feature
# config/local.yaml
executor:
    plugin: k8s-vm
    k8s-vm:
        options:
            kubernetes:
                host: YOUR-KUBERNETES-HOST
                token: JWT-FOR-AUTHENTICATING-KUBERNETES-REQUEST
            launchVersion: stable

Jenkins (jenkins)

jenkins executor を使用している場合、ビルドは Jenkins を使用して実行されます。

環境変数名 デフォルト値 説明
EXECUTOR_PLUGIN k8s デフォルトの executor (jenkins を設定してください)
LAUNCH_VERSION stable 使用する Launcher のバージョン
EXECUTOR_JENKINS_ENABLED true Jenkins executor を利用可能にするフラグ
EXECUTOR_JENKINS_HOST   Jenkins のホスト
EXECUTOR_JENKINS_PORT 8080 Jenkins のポート
EXECUTOR_JENKINS_USERNAME screwdriver Jenkins の username
EXECUTOR_JENKINS_PASSWORD   Jenkins へのリクエストを認証するのに使用する password/token
EXECUTOR_JENKINS_NODE_LABEL screwdriver Jenkisn slave の Node label
EXECUTOR_JENKINS_DOCKER_COMPOSE_COMMAND docker-compose docker-compose コマンドのパス
EXECUTOR_JENKINS_DOCKER_PREFIX '' コンテナにつけられる prefix
EXECUTOR_JENKINS_LAUNCH_VERSION stable 使用する Launcher container のタグ
EXECUTOR_JENKINS_DOCKER_MEMORY 4g メモリの制限 (docker run の --memory オプション)
EXECUTOR_JENKINS_DOCKER_MEMORY_LIMIT 6g swap を含めたメモリの制限 (docker run の --memory-swap オプション)
EXECUTOR_JENKINS_BUILD_SCRIPT '' ビルドを開始するコマンド
EXECUTOR_JENKINS_CLEANUP_SCRIPT '' ビルドシステムをクリーンアップするコマンド
EXECUTOR_JENKINS_CLEANUP_TIME_LIMIT 20 ジョブを削除する時間(秒)
EXECUTOR_JENKINS_CLEANUP_WATCH_INTERVAL 2 ジョブが停止しているかチェックするインターバル(秒)
# config/local.yaml
executor:
    plugin: jenkins
    jenkins:
        options:
            jenkins:
                host: jenkins.default
                port: 8080
                username: screwdriver
                password: YOUR-PASSWORD
            launchVersion: stable

Docker (docker)

Docker で実行するには docker executor を使用します。sd-in-a-box も Docker を使用して実行します。

環境変数名 デフォルト値 説明
EXECUTOR_PLUGIN k8s docker を指定します
LAUNCH_VERSION stable 使用する Launcher のバージョン
EXECUTOR_DOCKER_ENABLED true Docker executor を利用可能にするフラグ
EXECUTOR_DOCKER_DOCKER {} Dockerode の設定 (JSONオブジェクト)
EXECUTOR_PREFIX なし Pod 名につけられる prefix
# config/local.yaml
executor:
    plugin: docker
    docker:
        options:
            docker:
                socketPath: /var/lib/docker.sock
            launchVersion: stable

Queue (queue)

queue executorを使用すると、Resqueを含むRedisインスタンスを実行しているリモートキューサービスにビルドをキューすることができます。

環境変数名 デフォルト値 説明
EXECUTOR_PLUGIN k8s デフォルトの executor (queue を設定します)
# config/local.yaml
executor:
    plugin: queue
    queue: ''

Nomad (nomad)

以下の環境変数を設定します。

環境変数名 デフォルト値 説明
EXECUTOR_PLUGIN k8s デフォルトの executor (nomad を設定してください)
LAUNCH_VERSION latest 使用する Launcher のバージョン
EXECUTOR_NOMAD_ENABLED true Nomad executor を利用可能にするフラグ
NOMAD_HOST nomad.default Nomad のホスト (例: http://192.168.30.30:4646)
NOMAD_CPU 600 Nomad の cpu リソース(Mhz)
NOMAD_MEMORY 4096 Nomad のメモリリソース(MB)
EXECUTOR_PREFIX sd-build- Nomad のジョブ名につけられる prefix
# config/local.yaml
executor:
    plugin: nomad
    nomad:
        options:
            nomad:
                host: http://192.168.30.30:4646
            resources:
                cpu:
                    high: 600
                memory:
                    high: 4096
            launchVersion:  latest
            prefix:  'sd-build-'

通知プラグイン

現在、Email 通知Slack 通知をサポートしています。

これらの環境変数を設定します。

環境変数名 必須 デフォルト値 説明
NOTIFICATIONS いいえ {} 通知の設定を含むJSONオブジェクト

Email 通知

SMTPサーバとEmail通知を行う送信者のアドレスを設定します。

# config/local.yaml
notifications:
    email:
        username: your-username # オプション SMTP username
        password: your-password # オプション SMTP password
        host: smtp.yourhost.com
        port: 25
        from: example@email.com

認証の設定はまだ実装されていませんが、追加することは難しくないでしょう。私たちは nodemailer パッケージを使用しているため、認証機能はよくある nodemailer のセットアップと同様です。コントリビューションお待ちしています: screwdriver-cd/notifications-email

Slack 通知

Slack インスタンスに screwdriver-botSlack bot user を作成してください。 bot のための Slack トークンを生成して、それを Slack 通知の設定欄の token に以下のように設定してください。

# config/local.yaml
notifications:
    slack:
        defaultWorkspace: your-workspace
        workspaces:
            your-workspace:
                token: 'YOUR-SLACK-BOT-TOKEN-HERE'
            secondary-workspace:
                token: 'ANOTHER-SLACK-BOT-TOKEN-HERE'

カスタム通知

notifications-base を利用することで、カスタム通知パッケージを作成することができます。パッケージ名は screwdriver-notifications-<your-notification> の形である必要があります。

下記はEmail通知とカスタム通知を同時に使う場合の local.yaml の設定例です:

# config/local.yaml
notifications:
    email:
        host: smtp.yourhost.com
        port: 25
        from: example@email.com
    your-notification:
        foo: bar
        abc: 123

もし scoped package を使用したい場合は、設定は以下のようになります:

# config/local.yaml
notifications:
    your-notification:
        config:
            foo: bar
            abc: 123
        scopedPackage: '@scope/screwdriver-notifications-your-notification'

通知オプション

包括的な通知オプションがあれば、このセクションで設定します。

#config/local.yaml
notifications:
    options:
      throwValidationErr: false # デフォルト: true, バリデーションに失敗したときにエラーを出すかどうかの真偽値値
    slack:
        defaultWorkspace: your-workspace
        workspaces:
            your-workspace:
                token: 'YOUR-SLACK-BOT-TOKEN-HERE'
            secondary-workspace:
                token: 'ANOTHER-SLACK-BOT-TOKEN-HERE'
    email:
        host: smtp.yourhost.com
        port: 25
        from: example@email.com

ソース管理プラグイン

現在はGitHubとGitHub EnterpriseBitbucket.orgGitLabをサポートしています。対応機能の内訳はSCM対応表を確認してください。

ステップ1: OAuthアプリケーションをセットアップ

OAuthアプリケーションのセットアップと、OAuth Client ID及びSecretの取得が必要です。

GitHub:
  1. GitHub OAuth applications ページを開きます。
  2. 作成したアプリケーションをクリックし、OAuth Client IDとSecretを取得します。
  3. APIが動作しているホストのIPアドレスをHomepage URLAuthorization callback URLに入力します。
GitLab:
  1. GitLab applications ページを開きます。
  2. Redirect URIhttps://YOUR_IP/v4/auth/login/gitlab:gitlab.com/webを入力します。
  3. Save Applicationをクリックします。
Bitbucket.org:
  1. Bitbucket OAuth applications ページを開きます: https://bitbucket.org/account/user/{your-username}/api
  2. Add Consumerをクリックします。
  3. APIが動作しているホストのIPアドレスをURLCallback URL に入力します。

ステップ2:SCMプラグインの設定

下記の環境変数を設定します。

環境変数名 必須 デフォルト値 説明
SCM_SETTINGS はい {} JSON object with SCM settings
GitHubの例:
# config/local.yaml
scms:
    github:
        plugin: github
        config:
            oauthClientId: YOU-PROBABLY-WANT-SOMETHING-HERE # OAuth Client ID (アプリケーションキー) (https://developer.github.com/v3/oauth/)
            oauthClientSecret: AGAIN-SOMETHING-HERE-IS-USEFUL # OAuth Client Secret (アプリケーションsecret)
            secret: SUPER-SECRET-SIGNING-THING # webhooks署名用のパスワード(secret)
            gheHost: github.screwdriver.cd # [Optional] GitHub Enterpriseの場合のGHEホスト
            username: sd-buildbot # [Optional] checkoutするユーザネーム
            email: dev-null@screwdriver.cd # [Optional] checkoutするユーザのEmailアドレス
            https: false # [Optional] Screwdriver APIがHTTPSで動作しているか、デフォルトはfalse
            commentUserToken: A_BOT_GITHUB_PERSONAL_ACCESS_TOKEN # [Optional] GitHubのPRにコメントを書き込むためのトークン、"public_repo"のスコープが必要
            privateRepo: false # [Optional] プライベートレポジトリの read/write権限
            autoDeployKeyGeneration: false # [Optional] trueにすると、deploy keyの公開鍵と秘密鍵を自動で生成し、それぞれをビルドパイプラインとチェックアウト用の Github のリポジトリに追加します。
    ...
プライベートリポジトリ

プライベートレポジトリを使用する場合は、SCM_USERNAMESCM_ACCESS_TOKENsecrets として screwdriver.yamlに記述する必要があります。

メタPRコメント

メタPRコメントを有効にするためには、Git上でbotユーザを作成し、そのユーザでpublic_repoのスコープを持ったトークンを作成する必要があります。Githubで、新規にユーザを作成し、create a personal access tokenの説明に従ってスコープをpublic_repoに設定します。このトークンをコピーしてAPI config yaml内のscmsの設定内のcommentUserTokenとして設定します。

Deploy Keys

Deploy Keyは、単一のGitHubリポジトリへのアクセスが許可されているSSH鍵です。この鍵はGitHubのpersonal access tokenと反対に、個人のユーザアカウントではなくリポジトリに直接紐付けられてます。GitHubのpersonal access tokenは全てのリポジトリに対してユーザ単位でのアクセス権を与える一方、Deploy Keyは単一のリポジトリへのアクセスを許可します。アクセスの制限が可能となるため、privateリポジトリではDeploy Keyの利用をおすすめします。

パイプラインでDeploy Keyを利用したい場合、2つの方法があります:

Read-only SCM

SCMを読み取り専用にしたい場合には、SCMのパイプラインをchild pipelineとしてリストアップすることで、間接的にSCMのパイプラインを作成できるようになります。以下に、read-only SCMの設定を追加する例を記します。ユーザーはUIでSCMにログインすることはできません。

  1. read-onlyのSCMにHeadlessユーザーを作成します。そのユーザーにpersonal access tokenを作成します。
  2. read-only SCMの設定をします。(下記の例を参考にしてください)
  3. 設定したscmContextPOST https://YOUR_IP/v4/buildclustersにリクエストして新しいビルドクラスタを追加します。詳細はAPIを参照してください。リクエスト時のペイロードは以下のようになります:
    {
     "name": "readOnlyScm",
     "managedByScrewdriver": true,
     "maintainer": "foo@bar.com",
     "description": "Read-only open source mirror",
     "scmContext": "gitlab:gitlab.screwdriver.cd",
     "scmOrganizations": [],
     "isActive": true,
     "weightage": 100
    }
    
GitLabの例
# config/local.yaml
scms:
    ...
    # 下記はread-only SCMの例
    gitlab:
        plugin: gitlab
        config:
            oauthClientId: YOU-PROBABLY-WANT-SOMETHING-HERE # OAuth Client ID (アプリケーションキー)
            oauthClientSecret: AGAIN-SOMETHING-HERE-IS-USEFUL # OAuth Client Secret (アプリケーションsecret)
            gitlabHost: gitlab.screwdriver.cd # [Optional] GitLab enterpriseのホスト名
            commentUserToken: A_BOT_GITLAB_PERSONAL_ACCESS_TOKEN # [Optional] GitLabのPRにコメントを書き込むためのトークン
            https: false # [Optional] Screwdriver APIがHTTPSで動作しているか、デフォルトはfalse
            readOnly: # [Optional] read-only SCMのための設定
                enabled: true # trueに設定するとread-onlyモードが有効
                username: sd-buildbot # Headlessのユーザー名
                accessToken: GITLAB-TOKEN # リポジトリへのread-onlyアクセスとwebhooksの追加が可能なHeadless GitLabトークン
                cloneType: https # [Optional] sshまたはhttpsを設定、デフォルトはhttps
Bitbucket.orgの例
# config/local.yaml
scms:
    bitbucket:
        plugin: bitbucket
        config:
            oauthClientId: YOUR-APP-KEY # OAuth Client ID (アプリケーションキー)
            oauthClientSecret: YOUR-APP-SECRET # OAuth Client Secret (アプリケーションsecret)
            https: true # [Optional] Screwdriver APIがHTTPSで動作しているか、デフォルトはfalse
            username: sd-buildbot # [Optional] checkoutするユーザネーム
            email: dev-null@screwdriver.cd # [Optional] checkoutするユーザのEmailアドレス

Webhooks

以下の環境変数を設定します。

環境変数名 必須 デフォルト値 説明
SCM_USERNAME いいえ sd-buildbot 設定されたユーザでSCMトークンを取得します。ユーザがScrewdriverに有効なトークンを登録していなければ、このトークンを使用します。
IGNORE_COMMITS_BY いいえ [] このユーザ達からのコミットを無視します。
RESTRICT_PR いいえ none PRを制限します:all, none, branch, fork
# config/local.yaml
webhooks:
  username: SCM_USERNAME
  ignoreCommitsBy:
    __name: IGNORE_COMMITS_BY
    __format: json
  restrictPR: RESTRICT_PR

レートリミット

以下の環境変数を設定することで、認証トークンによるレートリミットを設定します。

環境変数名 デフォルト値 説明
RATE_LIMIT_VARIABLES '{ "enabled": false, "limit": 300, "duration": 300000 }' レートリミットを設定するJSON文字列

または以下のような config/local.yaml でデフォルト値を上書きできます。

# config/local.yaml
rateLimit:
    enabled: true
    # リクエスト回数を1分間で最大60回に制限する
    limit: 60
    duration: 60000

Canaryルーティング

ScrewdriverのKubernetesクラスタがnginx Canary ingressを利用している場合、この環境変数を設定することでAPIサーバに一定期間だけCookieをセットさせ、後続のAPIリクエストが同じCanaryのAPIポッドに割り振られるようにします。

環境変数名 説明
RELEASE_ENVIRONMENT_VARIABLES '{ "cookieName": "release", "cookieValue": "canary"}' リリース情報をJSON文字列で設定

あるいは、以下の config/local.yaml でデフォルト値を上書きします。

# config/local.yaml
# environment release information
release:
    mode: stable
    cookieName: release
    cookieValue: stable
    cookieTimeout: 2 # in minutes
    headerName: release
    headerValue: stable

Redisロックの設定

RedisロックはScrewdriver apiで使用されており、ビルドの更新が連続的に行われることを保証します。これを無効にすると、ビルド更新中にデータが失われたり、ビルドが開始されないことがあります。

Redisのロックを設定するために、これらの環境変数を設定します:

環境変数名 必須 デフォルト値 説明
REDLOCK_ENABLED はい false Redisロックの有効化
REDLOCK_RETRY_COUNT はい 200 ロック取得までの最大リトライ回数
REDLOCK_DRIFT_FACTOR いいえ 0.01 予想されるクロックドリフト
REDLOCK_RETRY_DELAY いいえ 500 再実行するまでの時間(ミリ秒)
REDLOCK_RETRY_JITTER いいえ 200 再実行時にランダムに加えられる最大時間(ミリ秒)
REDLOCK_REDIS_HOST はい 127.0.0.1 Redis ホスト
REDLOCK_REDIS_PORT はい 9999 Redis ポート
REDLOCK_REDIS_PASSWORD いいえ THIS-IS-A-PASSWORD Redis パスワード
REDLOCK_REDIS_TLS_ENABLED いいえ false Redis tls 有効
REDLOCK_REDIS_DATABASE いいえ 0 Redis db番号
# config/local.yaml
redisLock:
  # Redisロックを有効にするには、trueを設定します。
  enabled: true
  options:
    # ロック取得までの最大リトライ回数
    retryCount: 200
    # 予想されるクロックドリフト
    driftFactor: 0.01
    # 再試行するまでの時間(ミリ秒)
    retryDelay: 500
    # 再試行回数にランダムに追加される最大時間(ミリ秒)
    retryJitter: 200
    # Redisインスタンスの設定
    redisConnection:
        host: "127.0.0.1"
        port: 6379
        options:
            password: '123'
            tls: false
        database: 0
        prefix: ""

Dockerコンテナの拡張

Screwdriver.cdのDockerイメージを拡張したい場合は、カスタムBookendプラグインを使用してください。この章で全てをお伝えすることはできないですが、基本的な利用方法はお伝えできるでしょう。

ログの記録

以下の環境変数を設定するとより多くのログが出力されるようになります。

環境変数名 必須 デフォルト値 説明
LOG_AUDIT_ENABLED いいえ false trueにすると全てのAPIで呼び出し毎に Audit ログが出力されるようになります。
LOG_AUDIT_SCOPE いいえ [] 対象となるトークンのスコープ (e.g. pipeline, build, temporal, admin, guest, user)
# config/local.yaml
log:
  audit:
    # APIの呼び出し毎に Audit ログを出力するようにする場合はtrueにしてください
    enabled: false
    # 対象となるトークンのスコープ(pipeline, build, temporal, admin, guest, user)
    scope: []

ログの出力の例:

{"level":"info","message":"[Login] User tkyi get /v4/events/41/builds","timestamp":"2022-11-04T22:19:33.039Z"}
{"level":"info","message":"[Login] Pipeline 7 post /v4/pipelines/7/sync","timestamp":"2022-11-04T22:19:33.985Z"}

カスタムbookendを使用する

Screwdriver.cdのDokcerイメージを拡張したい場合、カスタムbookendが使用できます。

今回の例では、カスタムbookendをscmの前に実行します (設定されたSCMからコードをチェックアウトします)。bookendプラグインも環境変数で設定できるのですが、local.yamlを使って設定していきます。

以下にlocal.yamlの例を示します。

# local.yaml
---
  ...
bookends:
  default:
    setup:
      - my-custom-bookend
      - scm

拡張したDockerイメージをビルドするために、追加の依存をインストールするDockerfileの作成が必要です。もしlocal.yamlを後でマウントするのではなくDockerイメージに保存したければ、以下のようにDockerfileを作成してください。

# Dockerfile
FROM screwdrivercd/screwdriver:stable
# Install additional NPM bookend plugin
RUN cd /usr/src/app && /usr/local/bin/npm install my-custom-bookend
# Optionally save the configuration file in the image
ADD local.yaml /config/local.yaml

Dockerイメージをビルドしたら、Screwdriver.cdのクラスタにデプロイする必要があります。例えば、Kubernetesを使用している場合は、screwdrivercd/api:stableを作成したDockerイメージで置き換えます。

以下は、Kubernetesのデプロイ設定を更新する例です。

# partial Kubernetes configuration
  ...
spec:
  replicas: 1
  template:
    spec:
      containers:
      - name: screwdriver-api
        # The image name is the one you specified when built
        # The tag name is the tag you specified when built
        image: my_extended_docker_image_name:tag_name