Kubernetesのドキュメント

このリポジトリには、KubernetesのWebサイトとドキュメントをビルドするために必要な全アセットが格納されています。あなたの貢献をお待ちしています！

ドキュメントに貢献する

リポジトリの使い方

Hugo(Extended version)を使用してWebサイトをローカルで実行することも、コンテナランタイムで実行することもできます。コンテナランタイムを使用することを強くお勧めします。これにより、本番Webサイトとのデプロイの一貫性が得られます。

前提条件

このリポジトリを使用するには、以下をローカルにインストールする必要があります。

npm
Go
Hugo (Extended version)
Dockerなどのコンテナランタイム

[!NOTE] netlify.tomlのHUGO_VERSION環境変数で指定されたHugo extended versionをインストールしてください。

始める前に、依存関係をインストールしてください。リポジトリをクローンし、ディレクトリに移動します。

git clone https://github.com/kubernetes/website.git
cd website

KubernetesのWebサイトではDocsyというHugoテーマを使用しています。コンテナでWebサイトを実行する場合でも、以下を実行して、サブモジュールおよびその他の依存関係を取得することを強くお勧めします。

Windows

# サブモジュールの依存関係を取得
git submodule update --init --recursive --depth 1

Linux / other Unix

# サブモジュールの依存関係を取得
make module-init

コンテナを使ってウェブサイトを動かす

コンテナ内でサイトを構築するには、以下を実行してコンテナイメージを構築し、実行します。

# 環境変数$CONTAINER_ENGINEを設定することで、Docker以外のコンテナランタイムを使用することもできます
make container-serve

エラーが発生した場合はhugoコンテナの計算リソースが不足しています。これを解決するには、使用しているマシン(MacOSとWindows)でDockerが使用できるCPUとメモリを増やしてください。

ブラウザでhttp://localhost:1313にアクセスしてください。リポジトリ内のソースファイルに変更を加えると、HugoがWebサイトの内容を更新してブラウザに反映します。

Hugoを使ってローカル環境でWebサイトを動かす

ローカルで依存関係をインストールし、サイトを構築してテストするには、次のコマンドを実行します。

For macOS and Linux
```
npm ci
make serve
```

For Windows (PowerShell)

npm ci
hugo.exe server --buildFuture --environment development

これで、Hugoのサーバーが1313番ポートを使って起動します。使用しているブラウザでhttp://localhost:1313にアクセスしてください。リポジトリ内のソースファイルに変更を加えると、HugoがWebサイトの内容を更新してブラウザに反映します。

API reference pagesをビルドする

content/ja/docs/reference/kubernetes-apiに配置されているAPIリファレンスページはhttps://github.com/kubernetes-sigs/reference-docs/tree/master/gen-resourcesdocsを使ってSwagger Specification (OpenAPI Specification)からビルドされています。

新しいKubernetesリリースのためにリファレンスページをアップデートするには、次の手順を実行します:

api-ref-generatorサブモジュールを取得します:
```
git submodule update --init --recursive --depth 1
```

Swagger Specificationを更新します:

curl 'https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json' > api-ref-assets/api/swagger.json

api-ref-assets/config/内のtoc.yamlとfields.yamlを新しいリリースの変更に合わせます。
次に、ページをビルドします:
```
make api-reference
```
コンテナイメージからサイトを作成、サーブする事でローカルで結果をテストすることができます:
```
make container-image
make container-serve
```
APIリファレンスを見るために、ブラウザでhttp://localhost:1313/docs/reference/kubernetes-api/を開いてください。
新しいコントラクトのすべての変更が設定ファイルtoc.yamlとfields.yamlに反映されたら、新しく生成されたAPIリファレンスのページとともにPull Requestを作成します。

トラブルシューティング

error: failed to transform resource: TOCSS: failed to transform "scss/main.scss" (text/x-scss): this feature is not available in your current Hugo version

Hugoは、技術的な理由から2種類のバイナリがリリースされています。現在のウェブサイトはHugo Extendedバージョンのみに基づいて運営されています。リリースページで名前にextendedが含まれるアーカイブを探します。確認するには、hugo versionを実行し、extendedという単語を探します。

macOSにてtoo many open filesというエラーが表示される

macOS上でmake serveを実行した際に以下のエラーが表示される場合

ERROR 2020/08/01 19:09:18 Error: listen tcp 127.0.0.1:1313: socket: too many open files
make: *** [serve] Error 1

OS上で同時に開けるファイルの上限を確認してください。

launchctl limit maxfiles

続いて、以下のコマンドを実行します(https://gist.github.com/tombigel/d503800a282fcadbee14b537735d202cより引用)。

#!/bin/sh

# These are the original gist links, linking to my gists now.
# curl -O https://gist.githubusercontent.com/a2ikm/761c2ab02b7b3935679e55af5d81786a/raw/ab644cb92f216c019a2f032bbf25e258b01d87f9/limit.maxfiles.plist
# curl -O https://gist.githubusercontent.com/a2ikm/761c2ab02b7b3935679e55af5d81786a/raw/ab644cb92f216c019a2f032bbf25e258b01d87f9/limit.maxproc.plist

curl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxfiles.plist
curl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxproc.plist

sudo mv limit.maxfiles.plist /Library/LaunchDaemons
sudo mv limit.maxproc.plist /Library/LaunchDaemons

sudo chown root:wheel /Library/LaunchDaemons/limit.maxfiles.plist
sudo chown root:wheel /Library/LaunchDaemons/limit.maxproc.plist

sudo launchctl load -w /Library/LaunchDaemons/limit.maxfiles.plist

こちらはmacOSのCatalinaとMojaveで動作を確認しています。

SIG Docsに参加する

コミュニティのページを確認することで、SIG Docs Kubernetesコミュニティとの関わり方を学ぶことができます。

本プロジェクトのメンテナーには以下の方法で連絡することができます:

ドキュメントに貢献する

GitHubの画面右上にあるForkボタンをクリックすると、GitHubアカウントに紐付いた本リポジトリのコピーが作成されます。このコピーのことをフォークと呼びます。フォークリポジトリの中では好きなように変更を加えることができます。加えた変更をこのリポジトリに反映したい好きなタイミングで、フォークリポジトリからPull Requestを作成してください。

Pull Requestが作成されると、レビュー担当者が責任を持って明確かつ実用的なフィードバックを返します。Pull Requestの所有者は作成者であるため、自分自身で作成したPull Requestを編集し、フィードバックに対応するのはあなたの責任です。

また、状況によっては2人以上のレビュアーからフィードバックが返されたり、アサインされていないレビュアーからのフィードバックが来ることがある点も留意してください。

さらに、特定のケースにおいては、レビュアーがKubernetesの技術的なレビュアーに対してレビューを依頼することもあります。レビュー担当者はタイムリーにフィードバックを提供するために最善を尽くしますが、応答時間は状況に応じて異なる場合があります。

[!NOTE] ローカライゼーションにおいては、技術的なレビューを行うことはありません。技術的なレビューは英語版のドキュメントに対してのみ行われます。

Kubernetesのドキュメントへの貢献に関する詳細については以下のページを確認してください:

[!NOTE] 日本語のローカライゼーションを行う際は、Kubernetesのドキュメントを翻訳するが参照すべきガイドとなります。

新たなコントリビューターのためのアンバサダー

[!NOTE] 日本語のローカライゼーションに関する質問は、Slack #kubernetes-docs-ja チャンネルにてお気軽にお尋ねください。

コントリビュートする時に何か助けが必要なら、New Contributor Ambassadorsに聞いてみると良いでしょう。彼らはSIG Docsのapproverで、最初の数回のPull Requestを通して新しいコントリビューターを指導し助けることを責務としています。New Contributors Ambassadorsにコンタクトするには、Kubernetes Slackが最適な場所です。現在のSIG DocsのNew Contributor Ambassadorは次の通りです:

名前	Slack	GitHub
Sreeram Venkitesh	@sreeram.venkitesh	@sreeram-venkitesh

行動規範

Kubernetesコミュニティへの参加については、CNCFの行動規範によって管理されています。

ありがとうございます！

Kubernetesはコミュニティの参加によって成長しています。Webサイトおよびドキュメンテーションへの皆さんの貢献に感謝します！