第4章 devfileのオーサリング

4.1. devfile バージョン 1のオーサリング

本セクションでは、devfile の概念および 1.0 仕様の devfile を使用して CodeReady Workspaces ワークスペースを設定する方法を説明します。

4.1.1. devfile とは

devfile は、開発環境を記述し、定義するファイルです。

  • ソースコード。
  • ブラウザー IDE ツールやアプリケーションランタイムなどの開発コンポーネント。
  • 事前定義コマンドの一覧。
  • クローン作成するプロジェクト。

devfile は、CodeReady Workspaces が消費し、複数のコンテナーで構成されるクラウドワークスペースに変換する YAML ファイルです。devfile はリモートまたはローカルに保存できます。以下のような各種の方法で実行できます。

  • git リポジトリーのルートフォルダー、または機能ブランチを使用。
  • HTTP 経由でアクセス可能な一般にアクセスできる Web サーバーを使用。
  • ローカルでファイルとして使用、またはcrwctlを使用してデプロイ。
  • devfile のコレクション (devfile レジストリー として知られる) を使用。

ワークスペースの作成時に、CodeReady Workspaces はその定義を使用してすべてを開始し、必要なツールおよびアプリケーションランタイムのすべてのコンテナーを実行します。また、CodeReady Workspaces はファイルシステムボリュームをマウントして、ソースコードをワークスペースで利用できるようにします。

devfile は、プロジェクトのソースコードでバージョン管理できます。ワークスペースで古いメンテナンスブランチを修正する必要がある場合、プロジェクトの devfile は、ワークスペースの定義を古いブランチでの機能を開始するために必要な各種ツールと依存関係と共に提供します。これを使用してワークスペースをオンデマンドでインスタンス化します。

CodeReady Workspaces は、ワークスペースで使用するツールと共に devfile の最新の状態を維持します。

  • パス、git の場所、ブランチなどのプロジェクトの要素。
  • ビルド、実行、テスト、デバッグなどの日次タスクを実行するためのコマンド。
  • アプリケーションの実行に必要なコンテナーイメージを含むランタイム環境。
  • 開発者がワークスペースで使用するツール、IDE 機能、ヘルパーが含まれる Che-Theia プラグイン (例: Git、Java サポート、SonarLint、およびプルリクエスト)。

4.1.2. 最小の devfile

以下は、devfile で必要なコンテンツの最小コンテンツです。

apiVersion: 1.0.0
metadata:
  name: crw-in-crw-out

devfile の完全なサンプルについては、CodeReady Workspaces devfile.yaml の Red Hat CodeReady Workspaces を参照してください。

注記

パラメーター generateName または name を使用するかどうかは選択できますが、ユーザーはこれらのパラメーターのいずれかを選択し、定義する必要があります。両方の属性を指定すると、generateName は無視されます。「ワークスペース名の生成」 を参照してください。

metadata:
  generatedName:

または

metadata:
  name:

4.1.3. ワークスペース名の生成

自動生成されるワークスペース名のプレフィックスを指定するには、devfile で generateName パラメーターを設定します。

apiVersion: 1.0.0
metadata:
  generateName: crw-

ワークスペース名は <generateName>YYYYY 形式(例: che-2y7kp)になります。Y はランダムな [a-z0-9] 文字です。

ワークスペースの作成時に、以下の命名規則が適用されます。

  • name が定義される際に、これはワークスペース名 <name> として使用されます。
  • generateName のみが定義されている場合、これは生成される名前 <generateName>YYYYY のベースとして使用されます。
注記

factory を使用して作成されたワークスペースの場合、name または generateName を定義すると同じ結果になります。定義された値は、名前のプレフィックス <name>YYYYY または <generateName>YYYYY として使用されます。generateNamename の両方が定義されている場合は、generateName が優先されます。

4.1.4. プロジェクトの devfile の作成

本セクションでは、プロジェクト用に最小限の devfile を作成し、devfile に複数のプロジェクトを追加する方法を説明します。

4.1.4.1. 最小 devfile の作成

ワークスペースを実行するのに十分な最小の devfile は、以下の部分素で構成されます。

  • 仕様バージョン
  • 名前

プロジェクトのない最小 devfile の例

apiVersion: 1.0.0
metadata:
  name: minimal-workspace

追加の設定がない場合、デフォルトのエディターが含まれるワークスペースが CodeReady Workspaces サーバーで設定されるデフォルトのプラグインと共に起動します。Che-Theia は、CodeReady Workspaces Machine Exec プラグインと共にデフォルトのエディターとして設定されます。factory を使用して Git リポジトリー内でワークスペースを起動すると、指定のリポジトリーとブランチからのプロジェクトがデフォルトで作成されます。プロジェクト名は、リポジトリー名と一致します。

ワークスペースの機能を追加するために、以下の部分を追加します。

  • コンポーネントの一覧: 開発コンポーネントおよびユーザーランタイム
  • プロジェクトの一覧: ソースコードリポジトリー
  • コマンドの一覧: 開発環境の実行、ランタイム環境の起動など、ワークスペースコンポーネントを管理するためのアクション

プロジェクトを含む最小 devfile の例

apiVersion: 1.0.0
metadata:
  name: petclinic-dev-environment
projects:
  - name: petclinic
    source:
      type: git
      location: 'https://github.com/spring-projects/spring-petclinic.git'
components:
  - type: chePlugin
    id: redhat/java/latest

4.1.4.2. devfile の複数プロジェクトの指定

単一の devfile は、必要な宛先に対してクローン作成される複数のプロジェクトを定義できます。これらのプロジェクトは、ワークスペースの起動後にユーザーのワークスペース内に作成されます。

各プロジェクトについて、以下を指定します。

  • ソースリポジトリーのタイプ: これには .git または .zip を指定できます。詳細は、Devfile リファレンスのセクションを参照してください。
  • ソースリポジトリーの場所: Git リポジトリーまたは zip アーカイブへの URL。
  • オプションで、プロジェクトのクローンが作成されるディレクトリー。指定がない場合は、デフォルトのディレクトリーが使用されます。これは、プロジェクト名またはプロジェクトの Git リポジトリーに一致するディレクトリーです。

2 つのプロジェクトを含む devfile の例

以下の例では、プロジェクトの frontend および backend はユーザーのプロジェクトのサンプルとして機能します。各プロジェクトは別個のリポジトリーに置かれます。

  • backend プロジェクトには、CodeReady Workspaces ランタイムで暗黙的に定義される、ソースルート下の src/github.com/<github-organization>/<backend>/ ディレクトリーにクローン作成する特定の要件があります。
  • frontend プロジェクトは、ソースルート下の <frontend/> ディレクトリーにクローン作成されます。
apiVersion: 1.0.0
metadata:
  name: example-devfile
projects:
- name: <frontend>
  source:
    type: git
    location: https://github.com/<github-organization>/<frontend>.git
- name: <backend>
  clonePath: src/github.com/<github-organization>/<backend>
  source:
    type: git
    location: https://github.com/<github-organization>/<backend>.git

関連資料

すべての devfile コンポーネントの割り当てと使用可能な値についての詳細は、以下を参照してください。

以下のサンプル devfile は、適切な参照例です。

4.1.5. devfile リファレンス

本セクションでは、devfile の参照および devfile を構成するさまざまな要素を使用する方法について説明します。

4.1.5.1. devfile へのスキーマバージョンの追加

手順

  • devfile で schemaVersion 属性を定義します。

例4.1 devfile へのスキーマバージョンの追加

schemaVersion: 1.0.0

4.1.5.2. devfile への名前の追加

devfile への名前の追加は必須です。name および generateName はどちらも任意の属性ですが、少なくともそのうちの 1 つを定義する必要があります。

手順

  1. ワークスペースの静的名を指定するには、name 属性を定義します。

    devfile への静的名の追加

    schemaVersion: 1.0.0
    metadata:
      name: devfile-sample

  2. 自動生成されるワークスペース名のプレフィックスを指定するにはgenerateName 属性を定義し、name 属性を定義しません。ワークスペース名は <generateName>YYYYY 形式になります(例: devfile-sample-2y7kp)。Yはランダムな [a-z0-9] 文字です。

    生成された名前の devfile への追加

    schemaVersion: 1.0.0
    metadata:
      generateName: devfile-sample-

注記

factory を使用して作成されたワークスペースの場合、name または generateName を定義すると同じ結果になります。定義された値は、名前のプレフィックス <name>YYYYY または <generateName>YYYYY として使用されます。generateNamename の両方が定義されている場合は、generateName が優先されます。

4.1.5.3. devfile へのプロジェクトの追加

devfile は、1 つ以上のプロジェクトが含まれるように設計されています。これらのプロジェクトを開発するためのワークスペースが作成されます。プロジェクトは、devfile の projects セクションに追加されます。

単一 devfile の各プロジェクトには、以下が必要です。

  • 一意な名前
  • 指定されるソース

プロジェクトソースは、type および location の 2 つの必須の値で構成されます。

type
プロジェクトソースプロバイダーの種類。
location
プロジェクトソースの URL。

CodeReady Workspaces は以下のプロジェクトタイプをサポートします。

git
Git のソースを含むプロジェクト。この場所はクローンのリンクを参照します。
github
git と同じですが、GitHub でホストされるプロジェクト専用です。GitHub 固有の機能を使用しないプロジェクトには git を使用します。
zip
ZIP アーカイブのソースを含むプロジェクト。場所は ZIP ファイルを参照します。
4.1.5.3.1. プロジェクトソースタイプ: git
source:
    type: git
    location: https://github.com/eclipse-che/che-server.git
    startPoint: main           1
    tag: 7.34.0
    commitId: 36fe587
    branch: 7.34.x
    sparseCheckoutDir: core  2
1
startPoint: tagcommitId、および branch の一般的な値。startPointtagcommitId、および branch パラメーターは相互に排他的です。複数の値を指定すると、startPointtagcommitIdbranch の順に適用されます。
2
sparseCheckoutDir: sparse checkout Git 機能のテンプレート。これは、プロジェクトの一部 (通常は単一ディレクトリー) のみが必要な場合に役立ちます。

例4.2 sparseCheckoutDir パラメーター設定

  • ルートの my-module ディレクトリー (およびそのコンテンツ) のみを作成するには /my-module/ に設定されます。
  • 先頭のスラッシュ (my-module/) を省略して、プロジェクトに存在するすべての my-module ディレクトリーを作成します。たとえば、/addons/my-module/を含みます。

    最後のスラッシュは、指定される名前のディレクトリー (それらのコンテンツを含む) のみが作成されることを示します。

  • ワイルドカードを使用して、複数のディレクトリー名を指定します。たとえば、module-* を設定すると、module- で始まる指定のプロジェクトのすべてのディレクトリーがチェックアウトされます。

詳細は、Git ドキュメントで sparse checkout を参照してください。

4.1.5.3.2. プロジェクトソースタイプ: zip
source:
    type: zip
    location: http://host.net/path/project-src.zip
4.1.5.3.3. プロジェクトのクローンパスパラメーター: clonePath

clonePath パラメーターは、プロジェクトのクローンを作成するパスを指定します。パスは /projects/ ディレクトリーに相対的であり、/projects/ ディレクトリーから外すことはできません。デフォルト値はプロジェクト名です。

プロジェクトが含まれる devfile の例

apiVersion: 1.0.0
metadata:
  name: my-project-dev
projects:
  - name: my-project-resourse
    clonePath: resources/my-project
    source:
      type: zip
      location: http://host.net/path/project-res.zip
  - name: my-project
    source:
      type: git
      location: https://github.com/my-org/project.git
      branch: develop

4.1.5.4. devfile へのコンポーネントの追加

単一の devfile のコンポーネントにはそれぞれ一意の名前を指定する必要があります。

4.1.5.4.1. コンポーネントタイプ: cheEditor

id を定義してワークスペースで使用するエディターを記述します。devfile には、cheEditor タイプの 1 つのコンポーネントのみを含めることができます。

components:
  - alias: theia-editor
    type: cheEditor
    id: eclipse/che-theia/next

cheEditor がない場合、デフォルトのエディターがそのデフォルトのプラグインと共に提供されます。デフォルトのプラグインは、デフォルトと同じ id で明示的に定義されるエディターについて指定されます (バージョンが異なる場合でも同様です)。Che-Theia は、CodeReady Workspaces Machine Exec プラグインと共にデフォルトのエディターとして設定されます。

ワークスペースでエディターが必要にならないように指定するには、devfile 属性の editorFree:true 属性 を使用します。

4.1.5.4.2. コンポーネントタイプ: chePlugin

id を定義してワークスペース内のプラグインを記述します。devfile は、複数の chePlugin コンポーネントを含めることができます。

  components:
   - alias: exec-plugin
     type: chePlugin
     id: eclipse/che-machine-exec-plugin/latest

上記の両方のタイプで、CodeReady Workspaces プラグインレジストリーからの、スラッシュで区切られたパブリッシャー、プラグインの名前およびバージョンである ID を使用します。CodeReady Workspaces プラグインレジストリーは、デフォルトですべてのプラグインに latest バージョンを使用することに注意してください。

ID でカスタムプラグインを参照するには、カスタムプラグインレジストリーをビルドし、デプロイします。カスタムレジストリーイメージのビルドを参照してください。

4.1.5.4.3. 代替コンポーネントレジストリーの指定

cheEditor および chePlugin コンポーネントタイプの代替レジストリーを指定するには、registryUrl パラメーターを使用します。

  components:
   - alias: exec-plugin
     type: chePlugin
     registryUrl: https://my-customregistry.com
     id: eclipse/che-machine-exec-plugin/latest
4.1.5.4.4. 記述子にリンクしてコンポーネントを指定する

エディターまたはプラグイン id を使用して cheEditor または chePlugin を指定するのではなく、reference フィールドを使用して、通常 meta.yaml という名前のコンポーネント記述子への直接リンクを提供します。

  components:
   - alias: exec-plugin
     type: chePlugin
     reference: https://raw.githubusercontent.com.../plugin/1.0.1/meta.yaml

reference フィールドの URL は一般に公開されている必要があり、取得可能な meta.yaml ファイルを直接参照する必要があります。meta.yaml ファイルにリダイレクトするか、または直接参照しない URL により、ワークスペースの起動が失敗します。meta.yaml ファイルの公開に関する詳細は、「VS Code 拡張のメタデータの公開」 を参照してください。

注記

単一のコンポーネント定義で id および reference フィールドを組み合わせることはできません。それらは相互に排他的です。

4.1.5.4.5. chePlugin コンポーネント設定のチューニング

chePlugin コンポーネントを詳細に調整する必要がある場合があり、その場合はコンポーネントの設定を使用できます。この例は、プラグイン設定を使用して JVM を設定する方法を示しています。

  id: redhat/java/latest
  type: chePlugin
  preferences:
     java.jdt.ls.vmargs: '-noverify -Xmx1G -XX:+UseG1GC -XX:+UseStringDeduplication'

設定は配列として指定することもできます。

  id: redhat/java/latest
  type: chePlugin
  preferences:
     go.lintFlags: ["--enable-all", "--new"]

4.1.5.4.6. コンポーネントタイプ: kubernetes

OpenShift コンポーネントの一覧からの設定の適用を可能にする複雑なコンポーネントタイプ。

コンテンツは、コンポーネントのコンテンツを含むファイルを参照する reference 属性で指定できます。

  components:
    - alias: mysql
      type: kubernetes
      reference: petclinic.yaml
      selector:
        app.kubernetes.io/name: mysql
        app.kubernetes.io/component: database
        app.kubernetes.io/part-of: petclinic

または、このコンポーネントを持つ devfile を REST API に追加するには、referenceContent フィールドを使用して OpenShift List オブジェクトのコンテンツを devfile に組み込むことができます。

  components:
    - alias: mysql
      type: kubernetes
      reference: petclinic.yaml
      referenceContent: |
           kind: List
           items:
            -
             apiVersion: v1
             kind: Pod
             metadata:
              name: ws
             spec:
              containers:
              ... etc
4.1.5.4.7. コンテナーのエントリーポイントの上書き

OpenShift で認識される場合と同様です。

一覧には複数のコンテナーが含まれる場合があります (デプロイメントの Pod または Pod テンプレートに含まれる場合があります)。エントリーポイントの変更を適用するコンテナーを選択するには、以下を実行します。

エントリーポイントは、以下のように定義できます。

  components:
    - alias: appDeployment
      type: kubernetes
      reference: app-deployment.yaml
      entrypoints:
      - parentName: mysqlServer
        command: ['sleep']
        args: ['infinity']
      - parentSelector:
          app: prometheus
        args: ['-f', '/opt/app/prometheus-config.yaml']

entrypoints 一覧には、適用する command および args パラメーターと共にコンテナーを選択する場合の制約が含まれます。上記の例では、制約は parentName: mysqlServer であり、これにより mysqlServer という親オブジェクトで定義されるすべてのコンテナーにコマンドが適用されます。親オブジェクトは、参照ファイル (上記の例では app-deployment.yaml) で定義される一覧の最上位オブジェクトであることが想定されます。

その他のタイプの制約 (およびそれらの組み合わせ) も使用できます。

containerName
コンテナーの名前
parentName
上書きするコンテナーが (間接的に) 含まれる親オブジェクトの名前
parentSelector
親オブジェクトに必要なラベルのセット

これらの制約の組み合わせは、参照される OpenShift List 内のコンテナーを正確に特定するために使用されます。

4.1.5.4.8. コンテナー環境変数の上書き

OpenShift コンポーネントのエントリーポイントをプロビジョニングまたは上書きするには、以下のように設定します。

  components:
    - alias: appDeployment
      type: kubernetes
      reference: app-deployment.yaml
      env:
        - name: ENV_VAR
          value: value

これは、一時的なコンテンツの場合や、参照されるコンテンツを編集するためのアクセスがない場合に役立ちます。指定される環境変数は各 init コンテナーおよびすべての Pod および Deployment 内のコンテナーにプロビジョニングされます。

4.1.5.4.9. mount-source オプションの指定

プロジェクトのソースディレクトリーのマウントをコンテナーに指定するには、mountSources パラメーターを使用します。

   components:
      - alias: appDeployment
        type: kubernetes
        reference: app-deployment.yaml
        mountSources: true

有効にされている場合、プロジェクトソースマウントは指定されるコンポーネントのすべてのコンテナーに適用されます。このパラメーターは、chePlugin タイプのコンポーネントにも適用できます。

4.1.5.4.10. コンポーネントタイプ: dockerimage

ワークスペースでコンテナーのコンテナーイメージベースの設定を定義することが可能なコンポーネントタイプ。dockerimage タイプのコンポーネントは、カスタムツールをワークスペースに組み込みます。コンポーネントは、そのイメージによって特定されます。

 components:
   - alias: maven
     type: dockerimage
     image: quay.io/eclipse/che-java11-maven:nightly
     volumes:
       - name: mavenrepo
         containerPath: /root/.m2
     env:
       - name: ENV_VAR
         value: value
     endpoints:
       - name: maven-server
         port: 3101
         attributes:
           protocol: http
           secure: 'true'
           public: 'true'
           discoverable: 'false'
     memoryLimit: 1536M
     memoryRequest: 256M
     command: ['tail']
     args: ['-f', '/dev/null']

最小の dockerimage コンポーネントの例

apiVersion: 1.0.0
metadata:
    name: MyDevfile
components:
    - type: dockerimage
      image: golang
      memoryLimit: 512Mi
      command: ['sleep', 'infinity']

これはコンポーネントのタイプ dockerimage および、image属性名を指定し、通常の Docker の命名規則を使用してコンポーネントに使用されるイメージの名前を指定します。つまり、上記の type 属性は docker.io/library/golang:latest と等しくなります。

dockerimage コンポーネントには、Red Hat CodeReady Workspaces のイメージで提供される ツール の有効な統合に必要な追加のリソースおよび情報を使用してイメージを拡張するための数多くの機能が含まれています。

4.1.5.4.11. プロジェクトソースのマウント

dockerimage コンポーネントがプロジェクトソースにアクセスできるようにするには、mountSources 属性を true に設定する必要があります。

apiVersion: 1.0.0
metadata:
    name: MyDevfile
components:
    - type: dockerimage
      image: golang
      memoryLimit: 512Mi
      command: ['sleep', 'infinity']

ソースは、イメージの実行中のコンテナーで利用可能な CHE_PROJECTS_ROOT 環境変数に保存される場所にマウントされます。この場所はデフォルトで /projects に設定されます。

4.1.5.4.12. コンテナーエントリーポイント

dockerimagecommand 属性は、他の引数と共に、イメージから作成されるコンテナーの entrypoint コマンドを変更するために使用されます。Red Hat CodeReady Workspaces では、コンテナーを無限に実行して、コンテナーに接続し、任意のコマンドをいつでも実行できるようにする必要があります。sleep コマンドの可用性と infinity 引数のサポートは特定のイメージで使用されるベースイメージによって異なるため、CodeReady Workspaces はこの動作を独自に自動的に挿入することはできません。ただし、この機能を活用すると、たとえば、変更した設定で必要なサーバーを起動することなどが可能になります。

4.1.5.4.13. 永続ストレージ

任意のタイプのコンポーネントは、イメージ内の特定の場所にマウントするカスタムボリュームを指定することができます。ボリューム名はすべてのコンポーネントで共有されるため、このメカニズムを使用してコンポーネント間でファイルシステムを共有することもできることに留意してください。

dockerimage タイプのボリュームを指定する例:

apiVersion: 1.0.0
metadata:
  name: MyDevfile
components:
  - type: dockerimage
    image: golang
    memoryLimit: 512Mi
    mountSources: true
    command: ['sleep', 'infinity']
    volumes:
      - name: cache
        containerPath: /.cache

cheEditor/chePlugin タイプのボリュームを指定する例:

apiVersion: 1.0.0
metadata:
  name: MyDevfile
components:
  - type: cheEditor
    alias: theia-editor
    id: eclipse/che-theia/next
    env:
    - name: HOME
      value: $(CHE_PROJECTS_ROOT)
    volumes:
    - name: cache
      containerPath: /.cache

kubernetes/openshift タイプのボリュームを指定する例:

apiVersion: 1.0.0
metadata:
  name: MyDevfile
components:
  - type: openshift
    alias: mongo
    reference: mongo-db.yaml
    volumes:
    - name: mongo-persistent-storage
      containerPath: /data/db
4.1.5.4.14. コンポーネントのコンテナーメモリー制限の指定

dockerimagechePlugin、または cheEditor のコンテナーメモリー制限を指定するには、memoryLimit パラメーターを使用します。

  components:
   - alias: exec-plugin
     type: chePlugin
     id: eclipse/che-machine-exec-plugin/latest
     memoryLimit: 1Gi
   - alias: maven
     type: dockerimage
     image: quay.io/eclipse/che-java11-maven:nightly
     memoryLimit: 512M

この制限は、指定されるコンポーネントのすべてのコンテナーに適用されます。

cheEditor および chePlugin コンポーネントタイプの場合、RAM 制限はプラグイン記述子ファイル (通常は meta.yaml という名前) で記述できます。

指定がない場合は、システム全体のデフォルトが適用されます (CHE_WORKSPACE_SIDECAR_DEFAULT__MEMORY__LIMIT__MB システムプロパティーの説明を参照)。

4.1.5.4.15. コンポーネントのコンテナーメモリー要求の指定

dockerimagechePlugin、または cheEditor のコンテナーメモリー要求を指定するには、memoryRequest パラメーターを使用します。

  components:
   - alias: exec-plugin
     type: chePlugin
     id: eclipse/che-machine-exec-plugin/latest
     memoryLimit: 1Gi
     memoryRequest: 512M
   - alias: maven
     type: dockerimage
     image: quay.io/eclipse/che-java11-maven:nightly
     memoryLimit: 512M
     memoryRequest: 256M

この制限は、指定されるコンポーネントのすべてのコンテナーに適用されます。

cheEditor および chePlugin コンポーネントタイプの場合、RAM 要求はプラグイン記述子ファイル (通常は meta.yaml という名前) で記述できます。

指定がない場合は、システム全体のデフォルトが適用されます(CHE_WORKSPACE_SIDECAR_DEFAULT__MEMORY__REQUEST__MB の説明を参照)。

4.1.5.4.16. コンポーネントのコンテナー CPU 制限の指定

chePlugincheEditor、または dockerimage のコンテナー CPU 制限を指定するには、cpuLimit パラメーターを使用します。

  components:
   - alias: exec-plugin
     type: chePlugin
     id: eclipse/che-machine-exec-plugin/latest
     cpuLimit: 1.5
   - alias: maven
     type: dockerimage
     image: quay.io/eclipse/che-java11-maven:nightly
     cpuLimit: 750m

この制限は、指定されるコンポーネントのすべてのコンテナーに適用されます。

cheEditor および chePlugin コンポーネントタイプの場合、CPU 制限はプラグイン記述子ファイル (通常は meta.yaml という名前) で記述できます。

指定がない場合は、システム全体のデフォルトが適用されます(CHE_WORKSPACE_SIDECAR_DEFAULT__CPU__LIMIT__CORES の説明を参照)。

4.1.5.4.17. コンポーネントのコンテナー CPU 要求の指定

chePlugincheEditor、または dockerimage のコンテナー CPU 要求を指定するには、cpuRequest パラメーターを使用します。

  components:
   - alias: exec-plugin
     type: chePlugin
     id: eclipse/che-machine-exec-plugin/latest
     cpuLimit: 1.5
     cpuRequest: 0.225
   - alias: maven
     type: dockerimage
     image: quay.io/eclipse/che-java11-maven:nightly
     cpuLimit: 750m
     cpuRequest: 450m

この制限は、指定されるコンポーネントのすべてのコンテナーに適用されます。

cheEditor および chePlugin コンポーネントタイプの場合、CPU 要求はプラグイン記述子ファイル (通常は meta.yaml という名前) で記述できます。

指定がない場合は、システム全体のデフォルトが適用されます(CHE_WORKSPACE_SIDECAR_DEFAULT__CPU__REQUEST__CORES の説明を参照)。

4.1.5.4.18. 環境変数

Red Hat CodeReady Workspaces では、コンポーネントの設定で利用可能な環境変数を変更して、Docker コンテナーを設定できます。環境変数は、コンポーネントタイプdockerimagechePlugincheEditorkubernetesopenshift でサポートされます。コンポーネントに複数のコンテナーがある場合、環境変数は各コンテナーにプロビジョニングされます。

apiVersion: 1.0.0
metadata:
  name: MyDevfile
components:
  - type: dockerimage
    image: golang
    memoryLimit: 512Mi
    mountSources: true
    command: ['sleep', 'infinity']
    env:
      - name: GOPATH
        value: $(CHE_PROJECTS_ROOT)/go
  - type: cheEditor
    alias: theia-editor
    id: eclipse/che-theia/next
    memoryLimit: 2Gi
    env:
    - name: HOME
      value: $(CHE_PROJECTS_ROOT)
注記
  • 変数の拡張は環境変数間で機能し、この場合、変数の参照に Kubernetes の命名規則が使用されます。
  • 事前定義された変数は、カスタム定義で使用できます。

以下の環境変数は、CodeReady Workspaces サーバーで事前に設定されます。

  • CHE_PROJECTS_ROOT: プロジェクトディレクトリーの場所 (コンポーネントがソースをマウントしないと、プロジェクトにアクセスできない点に注意してください)。
  • CHE_WORKSPACE_LOGS_ROOT__DIR: すべてのコンポーネントに共通するログの場所。コンポーネントでこのディレクトリーにログを配置する選択をする場合、ログファイルは他のすべてのコンポーネントからアクセスできます。
  • CHE_API_INTERNAL: CodeReady Workspaces サーバーとの通信に使用される CodeReady Workspaces サーバー API エンドポイントへの URL。
  • CHE_WORKSPACE_ID: 現行ワークスペースの ID。
  • CHE_WORKSPACE_NAME: 現行ワークスペースの名前。
  • CHE_WORKSPACE_NAMESPACE: 現行ワークスペースの CodeReady Workspaces プロジェクト。この環境変数は、ワークスペースが属するユーザーまたは組織の名前です。これは、ワークスペースがデプロイされる OpenShift プロジェクトとは異なることに注意してください。
  • CHE_MACHINE_TOKEN: CodeReady Workspaces サーバーに対する要求の認証に使用されるトークン。
  • CHE_MACHINE_AUTH_SIGNATURE__PUBLIC__KEY: CodeReady Workspaces サーバーとの通信のセキュリティーを保護するために使用するパブリックキー。
  • CHE_MACHINE_AUTH_SIGNATURE__ALGORITHM: CodeReady Workspaces サーバーとのセキュリティーが保護された通信で使用される暗号化アルゴリズム。

devfile は、コンポーネントのコンテナーでクローン作成されたプロジェクトを見つけるために CHE_PROJECTS_ROOT 環境変数のみが必要になる場合があります。さらに高度な devfile は、CHE_WORKSPACE_LOGS_ROOT__DIR 環境変数を使用してログを読み取る場合があります。CodeReady Workspaces サーバーにセキュアにアクセスするための環境変数は devfile の範囲外です。これらの変数は、高度なユースケースに使用する CodeReady Workspaces プラグインでのみ利用できます。

4.1.5.4.19. エンドポイント

すべてのタイプのコンポーネントは、Docker イメージが公開するエンドポイントを指定できます。これらのエンドポイントは、CodeReady Workspaces クラスターが Kubernetes Ingress または OpenShift ルートを使用して実行されており、これがワークスペース内の他のコンポーネントに対して実行されている場合にユーザーがアクセスすることができます。アプリケーションまたはデータベースサーバーがポートでリッスンし、これと直接対話できるようにするか、または他のコンポーネントがこれと対話できるようにする必要がある場合は、アプリケーションまたはデータベースのエンドポイントを作成できます。

エンドポイントには、以下の例のように複数のプロパティーがあります。

apiVersion: 1.0.0
metadata:
  name: MyDevfile
projects:
  - name: my-go-project
    clonePath: go/src/github.com/acme/my-go-project
    source:
      type: git
      location: https://github.com/acme/my-go-project.git
components:
  - type: dockerimage
    image: golang
    memoryLimit: 512Mi
    mountSources: true
    command: ['sleep', 'infinity']
    env:
      - name: GOPATH
        value: $(CHE_PROJECTS_ROOT)/go
      - name: GOCACHE
        value: /tmp/go-cache
    endpoints:
     - name: web
       port: 8080
       attributes:
         discoverable: false
         public: true
         protocol: http
  - type: dockerimage
    image: postgres
    memoryLimit: 512Mi
    env:
      - name: POSTGRES_USER
        value: user
      - name: POSTGRES_PASSWORD
        value: password
      - name: POSTGRES_DB
        value: database
    endpoints:
      - name: postgres
        port: 5432
        attributes:
          discoverable: true
          public: false

ここで、それぞれが単一のエンドポイントを定義する 2 つの Docker イメージがあります。エンドポイントは、ワークスペース内または (UI などを使用して) パブリックにアクセス可能なポートです。各エンドポイントには、名前とポート (コンテナー内で実行している特定のサーバーがリッスンしているポート) があります。以下は、エンドポイントに設定できるいくつかの属性です。

  • discoverable: エンドポイントが検出可能である場合、そのエンドポイントをワークスペースコンテナー内のホスト名として使用してアクセスできます (OpenShift のコンテキストでは、そのサービスが指定された名前で作成されます)。55
  • public: エンドポイントはワークスペース外からもアクセスできます (このエンドポイントは CodeReady Workspaces ユーザーインターフェースからアクセスできます)。このエンドポイントは、ポート 80 または 443 で常に公開されます (tls が CodeReady Workspaces で有効にされるかどうかによって異なります)。
  • protocol: パブリックエンドポイントの場合、プロトコルはエンドポイントアクセスの URL の作成方法についての UI に対するヒントとなります。一般的な値は httphttpswswss です。
  • secure: エンドポイントがアクセスの付与に JWT ワークスペーストークンを必要とする JWT プロキシーの背後に配置するかどうかを指定するブール値 (デフォルトは false)。JWT プロキシーはサーバーと同じ Pod にデプロイされ、サーバーは 127.0.0.1 などのローカルループバックインターフェースでのみリッスンすることを前提としています。

    警告

    ローカルループバック以外のインターフェースをリッスンすると、このサーバーは対応する IP アドレスのクラスターネットワーク内に JWT 認証がなくてもアクセスできるため、セキュリティー上のリスクが発生します。

  • path: エンドポイントへの URL のパスの部分です。これはデフォルトで / に設定されます。つまり、エンドポイントはコンポーネントによって定義されるサーバーの Web ルートでアクセスできることを前提としています。
  • unsecuredPaths: secure 属性が true に設定されていても、セキュアでない状態のままになるエンドポイントパスのコンマ区切りの一覧。
  • cookiesAuthEnabled: true (デフォルトは false) に設定すると、JWT ワークスペーストークンは自動的にフェッチされ、ワークスペース固有の Cookie に組み込まれ、要求による JWT プロキシーのパススルーが許可されます。

    警告

    この設定は、POST 要求を使用するサーバーと併用される場合に CSRF 攻撃を生じさせる可能性があります。

コンポーネント内で新規サーバーを起動すると、CodeReady Workspaces はこれを検出し、UI はこのポートを public ポートとして自動的に公開します。この動作は、たとえば Web アプリケーションのデバッグに役立ちます。コンテナーの起動時に自動的に起動するデータベースサーバーなど、サーバーではこれを実行できません。このコンポーネントについては、エンドポイントを明示的に指定します。

kubernetes/openshift および chePlugin/cheEditor タイプのエンドポイントを指定する例:

apiVersion: 1.0.0
metadata:
  name: MyDevfile
components:
  - type: cheEditor
    alias: theia-editor
    id: eclipse/che-theia/next
    endpoints:
    - name: 'theia-extra-endpoint'
      port: 8880
      attributes:
        discoverable: true
        public: true

  - type: chePlugin
    id: redhat/php/latest
    memoryLimit: 1Gi
    endpoints:
    - name: 'php-endpoint'
      port: 7777

  - type: chePlugin
    alias: theia-editor
    id: eclipse/che-theia/next
    endpoints:
    - name: 'theia-extra-endpoint'
      port: 8880
      attributes:
        discoverable: true
        public: true

  - type: openshift
    alias: webapp
    reference: webapp.yaml
    endpoints:
    - name: 'web'
      port: 8080
      attributes:
        discoverable: false
        public: true
        protocol: http

  - type: openshift
    alias: mongo
    reference: mongo-db.yaml
    endpoints:
    - name: 'mongo-db'
      port: 27017
      attributes:
        discoverable: true
        public: false
4.1.5.4.20. OpenShift リソース

複雑なデプロイメントを記述するには、devfile に OpenShift リソース一覧への参照を含めます。OpenShift リソース一覧はワークスペースの一部になります。

重要
  • CodeReady Workspaces は、OpenShift リソース一覧のすべてのリソースを単一のデプロイメントにマージします。
  • 名前の競合やその他の問題が生じないように、十分注意してこの一覧を準備してください。

表4.1 サポートされる OpenShift リソース

プラットフォームサポートされるリソース

OpenShift

deploymentspodsservicespersistent volume claimssecretsConfigMapsRoutes

apiVersion: 1.0.0
metadata:
  name: MyDevfile
projects:
  - name: my-go-project
    clonePath: go/src/github.com/acme/my-go-project
    source:
      type: git
      location: https://github.com/acme/my-go-project.git
components:
  -  type: kubernetes
     reference: ../relative/path/postgres.yaml

上記のコンポーネントは、devfile 自体の場所と相対的なファイルを参照します。つまり、この devfile は、devfile の場所を指定する CodeReady Workspaces factory によってのみ読み込み可能であるため、参照される OpenShift リソース一覧の場所を特定することができます。

以下は postgres.yaml ファイルの例です。

apiVersion: v1
kind: List
items:
-
    apiVersion: v1
    kind: Deployment
    metadata:
        name: postgres
        labels:
            app: postgres
    spec:
        template:
        metadata:
            name: postgres
            app:
                name: postgres
        spec:
            containers:
            - image: postgres
              name: postgres
              ports:
              - name: postgres
                containerPort: 5432
                volumeMounts:
                - name: pg-storage
                  mountPath: /var/lib/postgresql/data
            volumes:
            - name: pg-storage
              persistentVolumeClaim:
                  claimName: pg-storage
-
    apiVersion: v1
    kind: Service
    metadata:
        name: postgres
        labels:
            app: postgres
            name: postgres
    spec:
        ports:
            - port: 5432
              targetPort: 5432
        selector:
            app: postgres
-
    apiVersion: v1
    kind: PersistentVolumeClaim
    metadata:
        name: pg-storage
      labels:
        app: postgres
    spec:
        accessModes:
         - ReadWriteOnce
        resources:
            requests:
                storage: 1Gi

関連付けられた OpenShift 一覧を含む devfile の基本的な例については、redhat-developer GitHub の web-nodejs-with-db-sample を参照してください。

リソースのサブセットのみを必要とする汎用または大規模なリソース一覧を使用する場合は、セレクター (通常は OpenShift セレクターとして一覧にあるリソースラベルで機能する) を使用して、一覧から特定のリソースを選択できます。

apiVersion: 1.0.0
metadata:
  name: MyDevfile
projects:
  - name: my-go-project
    clonePath: go/src/github.com/acme/my-go-project
    source:
      type: git
      location: https://github.com/acme/my-go-project.git
components:
  - type: kubernetes
    reference: ../relative/path/postgres.yaml
    selector:
      app: postgres

また、リソース一覧のコンテナーのエントリーポイント (コマンドおよび引数) を変更することもできます。

4.1.5.5. devfile へのコマンドの追加

devfile を使用すると、ワークスペースで実行できるコマンドを指定できます。すべてのコマンドにはアクションのサブセットが含まれますが、それらは実行されるコンテナーの特定のコンポーネントに関連するものです。

 commands:
   - name: build
     actions:
       - type: exec
         component: mysql
         command: mvn clean
         workdir: /projects/spring-petclinic

コマンドを使用するとワークスペースを自動化できます。コードをビルドし、テストするか、またはデータベースのクリーニングを実行するためのコマンドを定義できます。

以下は、2 種類のコマンドです。

  • CodeReady Workspaces 固有のコマンド: コマンドを実行するコンポーネントを完全に制御できます。
  • エディター固有のコマンド: エディター固有のコマンド定義を使用できます (例: Che-Theia の tasks.json および launch.json。これは、VS Code でのこれらのファイルの動作と同等です)。
4.1.5.5.1. CodeReady Workspaces 固有のコマンド

CodeReady Workspaces 固有のコマンドの機能

  • 実行するコマンドを指定する actions 属性。
  • コマンドを実行するコンテナーを指定する component 属性。

コマンドは、コンテナーのデフォルトシェルを使用して実行します。

apiVersion: 1.0.0
metadata:
  name: MyDevfile
projects:
  - name: my-go-project
    clonePath: go/src/github.com/acme/my-go-project
    source:
      type: git
      location: https://github.com/acme/my-go-project.git
components:
  - type: dockerimage
    image: golang
    alias: go-cli
    memoryLimit: 512Mi
    mountSources: true
    command: ['sleep', 'infinity']
    env:
      - name: GOPATH
        value: $(CHE_PROJECTS_ROOT)/go
      - name: GOCACHE
        value: /tmp/go-cache
commands:
  - name: compile and run
    actions:
     - type: exec
       component: go-cli
       command: “go get -d && go run main.go”
       workdir: “${CHE_PROJECTS_ROOT}/src/github.com/acme/my-go-project”
注記
  • コマンドで使用されるコンポーネントにはエイリアスが必要です。このエイリアスは、コマンド定義でコンポーネントを参照するために使用されます。例: コンポーネント定義の alias: go-cli およびコマンド定義の component: go-cli。これにより、Red Hat CodeReady Workspaces がコマンドを実行できる正しいコンテナーを検索できます。
  • コマンドには 1 つのアクションのみを指定できます。
4.1.5.5.2. エディター固有のコマンド

ワークスペースのエディターがサポートする場合、devfile はエディター固有の形式で追加の設定を指定できます。これはワークスペースエディター自体にある統合コードに依存するため、汎用的なメカニズムではありません。ただし、Red Hat CodeReady Workspaces 内のデフォルトの Che-Theia エディターは、devfile で提供される tasks.json および launch.json ファイルを把握できるように機能します。

apiVersion: 1.0.0
metadata:
  name: MyDevfile
projects:
  - name: my-go-project
    clonePath: go/src/github.com/acme/my-go-project
    source:
      type: git
      location: https://github.com/acme/my-go-project.git
commands:
  - name: tasks
    actions:
      - type: vscode-task
        referenceContent: >
            {
                "version": "2.0.0",
                "tasks": [
                    {
                        "label": "create test file",
                        "type": "shell",
                        "command": "touch ${workspaceFolder}/test.file"
                    }
                ]
            }

この例では、devfile と tasks.json ファイルの関連付けを示しています。このコマンドをタスク定義として解釈するよう Che-Theia エディターに指示する vscode-task タイプと、ファイル自体のコンテンツを含む referenceContent 属性があることに留意してください。このファイルを devfile とは別に保存し、reference 属性を使用して相対パスまたは絶対 URL を指定することもできます。

vscode-task コマンドのほかにも、Che-Theia エディターは起動設定を指定して vscode-launch タイプを認識します。

4.1.5.5.3. コマンドプレビュー URL

Web UI を公開するコマンドのプレビュー URL を指定できます。この URL は、コマンドの実行時に開けるように提供されます。

commands:
    - name: tasks
      previewUrl:
        port: 8080     1
        path: /myweb   2
      actions:
      - type: exec
        component: go-cli
        command: "go run webserver.go"
        workdir: ${CHE_PROJECTS_ROOT}/webserver
1
アプリケーションがリッスンする TCP ポート。必須パラメーター。
2
UI への URL のパスの部分。オプションのパラメーター。デフォルトは root (/) です。

上記の例では、http://__<server-domain>__/myweb が開きます。ここで、<server-domain> は動的に作成される OpenShift Route の URL です。

4.1.5.5.3.1. プレビュー URL を開くデフォルトの方法の設定

デフォルトで、URL を開く際の設定についてユーザーに尋ねる通知が表示されます。

サービス URL のプレビューに使用する推奨される方法を指定するには、以下を実行します。

  1. File → Settings → Open Preferences で CodeReady Workspaces 設定を開き、CodeReady Workspaces セクションで che.task.preview.notifications を見つけます。
  2. 使用できる値の一覧から選択します。

    • on —URL を開く際の設定についてユーザーに尋ねる通知を有効にします。
    • alwaysPreview — プレビュー URL は、タスクが実行されるとすぐに自動的に Preview パネルで開きます。
    • alwaysGoTo —プレビュー URL は、タスクが実行されるとすぐに別のブラウザータブで自動的に開きます。
    • off —プレビュー URL を開くを無効にします (自動的に無効にし、通知を出します)。

4.1.5.6. devfile への属性の追加

devfile 属性を使用して、各種の機能を設定することもできます。

4.1.5.6.1. 属性: editorFree

エディターが devfile で指定されない場合、デフォルトが指定されます。エディターが必要ない場合は、editorFree 属性を使用します。デフォルト値の false は、devfile がデフォルトエディターのプロビジョニングを要求することを意味します。

エディターのない devfile の例

apiVersion: 1.0.0
metadata:
  name: petclinic-dev-environment
components:
  - alias: myApp
    type: kubernetes
    reference: my-app.yaml
attributes:
  editorFree: true

4.1.5.6.2. 属性: persistVolumes(一時モード)

デフォルトで、devfile で指定されるボリュームおよび PVC は、コンテナーの再起動後もデータを永続化させるためにホストフォルダーにバインドされます。ボリュームのバックエンドの速度が遅い場合など、データの永続性を無効にしてワークスペースをより高速にするには、devfile の persistVolumes 属性を変更します。デフォルト値は true です。設定されたボリュームおよび PVC に emptyDir を使用するには、false に設定します。

一時モードが有効にされた devfile の例

apiVersion: 1.0.0
metadata:
  name: petclinic-dev-environment
projects:
  - name: petclinic
    source:
      type: git
      location: 'https://github.com/che-samples/web-java-spring-petclinic.git'
attributes:
  persistVolumes: false

4.1.5.6.3. 属性: asyncPersist (非同期ストレージ)

persistVolumesfalse に設定されている場合(上記を参照)は、追加の属性 asyncPersisttrue に設定して非同期ストレージを有効にすることができます。詳細は、ストレージタイプの設定を参照してください。

非同期ストレージが有効にされている devfile の例

apiVersion: 1.0.0
metadata:
  name: petclinic-dev-environment
projects:
  - name: petclinic
    source:
      type: git
      location: 'https://github.com/che-samples/web-java-spring-petclinic.git'
attributes:
  persistVolumes: false
  asyncPersist: true

4.1.5.6.4. 属性: mergePlugins

このプロパティーは、プラグインをワークスペースに追加する方法を手動で制御できるようにするために設定できます。mergePlugins プロパティーが true に設定されている場合、Che はプラグインを組み合わせて同じコンテナーの複数のインスタンスの実行を回避するよう試行します。このプロパティーが devfile に含まれない場合のデフォルト値は Che 設定プロパティー che.workspace.plugin_broker.default_merge_plugins で制御されます。mergePlugins: false 属性を devfile に追加すると、そのワークスペースのプラグインのマージが無効になります。

プラグインのマージが無効にされている devfile の例

apiVersion: 1.0.0
metadata:
  name: petclinic-dev-environment
projects:
  - name: petclinic
    source:
      type: git
      location: 'https://github.com/che-samples/web-java-spring-petclinic.git'
attributes:
  mergePlugins: false

4.1.6. Red Hat CodeReady Workspaces 2.11 でサポートされるオブジェクト

以下の表は、Red Hat CodeReady Workspaces 2.11 で部分的にサポートされるオブジェクトの一覧です。

オブジェクトAPIKubernetes インフラストラクチャーOpenShift インフラストラクチャー

Pod

Kubernetes

Yes

Yes

-

デプロイメント

Kubernetes

Yes

Yes

-

ConfigMap

Kubernetes

Yes

Yes

-

PVC

Kubernetes

Yes

Yes

-

Secret

Kubernetes

Yes

Yes

-

サービス

Kubernetes

Yes

Yes

-

Ingress

Kubernetes

Yes

No

minishift を使用すると Ingress を作成でき、これはホストが指定されていると機能します (OpenShift はそのルートを作成します)。ただし、loadBalancer IP はプロビジョニングされません。OpenShift インフラストラクチャーノードの Ingress サポートを追加するには、提供される Ingress に基づいてルートを生成します。

Route

OpenShift

No

Yes

OpenShift recipe は Kubernetes インフラストラクチャーと互換性を持たせる必要があります。OpenShiftルートはIngressesで置き換えられます。

Template

OpenShift

Yes

Yes

Kubernetes API はテンプレートをサポートしません。recipe 内のテンプレートを使用するワークスペースが正常に開始し、デフォルトのパラメーターが解決されます。