gcloud config / kubectl config 事始め。
手元のgcloudに紐付く複数のaccount
/project
/k8s cluster
/k8s namespace
を持っている場合、とにかくどのアカウントで、何のロールで、どこのプロジェクトのどのクラスタに向かってgcloudやkubectlを叩いているのか都度確認しながら作業することになる。gcloudとkubectlはそれぞれconfig
というリクエストの投げ先(context
)の設定をするのに重要なサブコマンドを持っていて、これらを正しく設定しないと所望のプロジェクトなりクラスタにアクセスできない。サブコマンドがどちらもconfigという名前なので、慣れてくると覚えるキーワードが少なくて大変良いが、頭の中で二つを整理しないうちは似たようなコマンドが色々出てくるので何が何やらわからなくなってくる。
また、個々の設定方法はコマンドのhelpなりドキュメントを見ればわかるが、最初は脳内に逆引き辞書的なものが存在しないので、そもそも必要なコマンドに辿り着けない。gcloud cheat sheetとかで調べればやり方的なものは出てくるけど、結局自分で触ったものしか理解できないし何より全然覚えないので、観念して自前のチートシートを書き溜めることにした。
ここではサブコマンドconfig
に関わるものを中心に、クラウド上にリソースを作り始めたりする前に確認しておきたい事柄(バージョンやパーミッションなど)を書き下す。
- コマンドのインストール
- account/project/region/zoneをまとめて扱うnamed configurationsの設定と切り替え
- GKE上にk8sクラスタを作成
- master/nodeのバージョン確認とアップグレード
- kubectlのcontext設定とnamespaceの設定と切り替え
- kubectlに既存のk8sクラスタを認識させる (
get-credentials
) - kubectlのcontextとnamespaceの管理に便利なプロンプトとCLIの導入
- user/service accountのロールとパーミッション確認方法
Installations
まず必要な物を手元に揃える。
Install gcloud
Command
(2018/11/22 更新) 公式に案内はないけどbrew cask
経由でインストールできる。
$ brew cask install google-cloud-sdk
$ gcloud --version
インストール後は定期的にアップデート。結構頻繁に更新される。
$ gcloud components update
Ref. Google Cloud SDK - Release Notes | Cloud SDK Documentation | Google Cloud
Install Other Packages
macosの場合。
brew install kubernetes-helm brew cask install minikube brew install stern brew install txn2/tap/kubefwd brew install kubectx brew install kube-ps1
sternはデバッグするのに超便利。kubefwdはデプロイしたserviceをローカルから試す際に個人的に必須のコマンド。kube-ps1
はプロンプトにcontextとnamespaceを表示してくれる(kubectx
と合わせて後述)。
Setup .zshrc
brew cask
でインストールした場合、brew cask info google-cloud-sdk
でタブ補完に何をsourceすべきか確認できる。
source '/usr/local/Caskroom/google-cloud-sdk/latest/google-cloud-sdk/path.zsh.inc' source '/usr/local/Caskroom/google-cloud-sdk/latest/google-cloud-sdk/completion.zsh.inc' if [ $commands[kubectl] ]; then source <(kubectl completion zsh) fi if [ $commands[helm] ]; then source <(helm completion zsh) fi
Ref. Install and Set Up kubectl - Kubernetes
Install Components
kubectlその他、使っているcomponentsをインストール。メジャーっぽいcomponentも平気でbeta, alphaだったりするので、これも入れておく。
$ gcloud components update $ gcloud components install kubectl $ gcloud components install cloud-build-local $ gcloud components install beta $ gcloud components install alpha $ gcloud components list
container-builder-localはローカルでContainer Builderと同じコンテナのビルドパイプラインを実行できる優れもの。
Ref. Taming Google Container Builder - Daisuke Maki - Medium
gcloud config
以下では、複数のconfigを作成して自由に切り替えられることを確認する。
Setup Named Configurations for Each Project
複数のaccount/project/clusterを持っている場合、named configurationsの設定を意識してしておくと良い。
topicという補足のhelpがあるのでこれでnamed configurationsの概要を掴む。書いてある通り、一つのaccount/project/clusterしか管理しないんだったらconfigurationsは忘れても良い。
$ gcloud topic configurations
このnamed configurationをproject/cluster毎に複数用意しておけば、gcloud config configurations activate [config name]
でconfigを切り替えられる。
Create New Configuration
gcloud init
は新しいnamed configurationsの設定や既存のnamed configurationsの再設定をインタラクティブ行う。
$ gcloud init
以下では、個別の設定を対応するサブコマンドで一つずつ設定していくが、やっていることは結果的にgcloud init
と同じ。
まず、以下のコマンドで現在設定済みのnamed configurationsのリストを確認。
$ gcloud config configurations list
新しいconfigを作成。
$ gcloud config configurations create my-config Created [my-config]. Activated [my-config].
設定ファイルの場所を確認。
$ gcloud info --format='get(config.paths.active_config_path)' /path/to/.config/gcloud/configurations/config_my-config
作成したconfigをlistで確認。作成したmy-config
が追加された。今はmy-configがactive。
$ gcloud config configurations list NAME IS_ACTIVE ACCOUNT PROJECT DEFAULT_ZONE DEFAULT_REGION default False [another account name] [another project] asia-east1-a asia-east1 my-config True
describeで空のconfigができたことを確認。ここからaccount/project/zone/regionを設定して、後で意図したGKEクラスタにアクセスできるように準備する。
$ gcloud config configurations describe my-config is_active: true name: my-config properties: {}
gcloud config list
で現在active状態のconfigを確認できる。設定している最中はこっちで見た方が混乱も間違いもない。
$ gcloud config list [core] disable_usage_reporting = False Your active configuration is: [my-config]
Setup auth
まずはaccountを設定する。初回ログイン時は認証のためにブラウザが起動する。
$ gcloud auth login [your account name] WARNING: `gcloud auth login` no longer writes application default credentials. If you need to use ADC, see: gcloud auth application-default --help You are now logged in as [your account name]. Your current project is [None]. You can change this setting by running: $ gcloud config set project PROJECT_ID
authしたメールアドレス([your account name]
)がaccountに設定されていることを確認。
$ gcloud config list [core] account = [your account name] disable_usage_reporting = False Your active configuration is: [my-config]
複数のgoogleアカウントでloginすることができる。loginしたgoogleアカウントをlistで確認。ここにはauthしたservice accountも含まれる。どのアカウントを使っているかはactivateしているconfigに依存する。
$ gcloud auth list $ gcloud auth describe [your account name]
Handle the error of google: could not find default credentials.
ずっと問題なく gcloud/kubectl
コマンドを使えていたのに、ある日突然以下のエラーが出て、GKEにアクセスできなくなった。
google: could not find default credentials. See https://developers.google.com/accounts/docs/application-default-credentials for more information.
$ gcloud auth application-default login
で再認証する。
gcloud auth login
, gcloud init
, gcloud config set account MY_ACCOUNT
等の認証とはまた別の話なので、慌てず gcloud auth application-default login
を叩く。
Ref. gcloud auth application-default login | Cloud SDK | Google Cloud
Ref. kubernetes - Could not find default credentials - Stack Overflow
Setup project
projectを設定する。authしたgoogleアカウントに紐付くprojectを確認。
$ gcloud projects list
所望のprojectを設定する。
$ gcloud config set project [your project name] Updated property [core/project].
Setup region
/zone
$ gcloud compute regions list $ gcloud config set compute/region asia-northeast1
$ gcloud compute zones list $ gcloud config set compute/zone asia-northeast1-a
Ref. Regions and Zones | Compute Engine Documentation | Google Cloud
これで最低限必要なconfigが揃った。
$ gcloud config list [compute] region = asia-northeast1 zone = asia-northeast1-a [core] account = [your account name] disable_usage_reporting = False project = [your project name] Your active configuration is: [my-config]
他のconfigからいつでもこのconfigに戻ってこれる。
$ gcloud config configurations activate my-config Activated [my-config].
ちなみにactive状態でない別のconfigを単発のgcloudコマンドに適用できる。
$ gcloud container clusters list --configuration=[another-config] $ export CLOUDSDK_ACTIVE_CONFIG_NAME=[another-config]; gcloud container clusters list
Manage k8s Cluster on GKE
ここでは上記で設定したconfigを元にGKE上にk8sのクラスタを新規作成、バージョンの確認、アップグレード、等を行う。
Create k8s clusters on GKE
現在のactivateになっているconfigを元にGKE上に最小のクラスタを立ち上げる。
$ gcloud config configurations list $ gcloud config list $ gcloud compute machine-types list $ gcloud container clusters create hands-on --machine-type=g1-small --num-nodes=1
余談: f1-micro
インスタンスタイプf1-micro
をus regionで起動すれば、1インスタンスまでは無料枠が適用される。
- 1
f1-micro
instance per month (US regions only, excluding Northern Virginia)
とあるようにus-east4 (Northern Virginia)
は無料にならないので注意。
ラッキー、k8s on GKEが無料!と思ってgcloud container clusters create
を叩いたらf1-micro
選ぶんだったらnodeは3つ起動しろと怒られた(2018/03/21時点)。残念。
ERROR: (gcloud.container.clusters.create) ResponseError: code=400, message=Clusters of f1-micro instances must contain at least 3 nodes. Please make the cluster larger or use a different machine type.
Ref. GCP Free Tier | Google Cloud Platform Free Tier | Google Cloud
Versioning and Upgrades
リリースノートを見るとバージョンは結構頻繁にアップグレードされるっぽい。
Ref. Release notes | Kubernetes Engine Documentation | Google Cloud
新しいクラスタに入るk8sのバージョンはstable releaseとしてdefaultClusterVersion
で指定されているバージョンで作成される。
The Kubernetes Engine team periodically performs automatic upgrades of your cluster masterto newer stable versions of Kubernetes.
とあるように、masterのアップグレードはほっといても自動で行われる(すげぇ)。
Ref. Versioning and upgrades | Kubernetes Engine Documentation | Google Cloud
Node Auto-Upgrades
--enable-autoupgrade
オプションでNode Auto-Upgradesを有効にしておけば、nodeのアップグレードも自動化できる(すげぇ)。
gcloud container clusters create --machine-type=g1-small --num-nodes=1 --enable-autoupgrade
nodeの自動アップグレード時、nodeは常にmasterのバージョンに追従する。
既存のクラスタは以下で有効化。
$ gcloud container node-pools list --cluster=hands-on # Check the target node pool name (default-pool) $ gcloud container node-pools update default-pool --cluster hands-on --zone asia-northeast1-a --enable-autoupgrade $ gcloud container clusters describe hands-on --format 'yaml(nodePools[].management)' # Check the updated config nodePools: - management: autoUpgrade: true
以下で無効化。
$ gcloud container node-pools update default-pool --cluster hands-on --zone asia-northeast1-a --no-enable-autoupgrade
Ref. Auto-upgrading nodes | Kubernetes Engine Documentation | Google Cloud
Node Auto-Repair
--enable-autorepair
でNodeの自動修復もできるっぽい。
Ref. Auto-repairing nodes | Kubernetes Engine Documentation | Google Cloud
既存のクラスタは以下で有効化。Node Auto-Upgradesと同様に、node poolの単位で設定可能。
$ gcloud container node-pools update default-pool --cluster hands-on --zone asia-northeast1-a --enable-autorepair $ gcloud container clusters describe hands-on --format 'yaml(nodePools[].management)' # Check the result nodePools: - management: autoRepair: true autoUpgrade: true
以下で無効化。
$ gcloud container node-pools update default-pool --cluster hands-on --zone asia-northeast1-a --no-enable-autorepair
修復は複数のnodeに対して同時に走る場合がある。また、一度走り出した修復は途中でNode Auto-Repairを無効化してもキャンセルされない。
Maintenance Window
自動アップグレードの時間帯を調整できる。
Ref. Maintenance window | Kubernetes Engine Documentation | Google Cloud
既存のクラスタには以下で設定。
$ gcloud container clusters update hands-on --maintenance-window 16:00 $ gcloud container clusters describe hands-on --format 'yaml(maintenancePolicy)' maintenancePolicy: window: dailyMaintenanceWindow: duration: PT4H0M0S startTime: '16:00'
以下で削除。
$ gcloud container clusters update hands-on --maintenance-window None
Upgrade k8s to the latest version
2018/06/30の時点では、defaultClusterVersion
は1.9.7-gke.3
になっている。
$ gcloud container get-server-config --zone asia-northeast1-a --format 'value(defaultClusterVersion)' Fetching server config for asia-northeast1-a 1.9.7-gke.3
作ったクラスタもdefaultClusterVersion
で指定されているバージョン。
$ gcloud container clusters list NAME LOCATION MASTER_VERSION MASTER_IP MACHINE_TYPE NODE_VERSION NUM_NODES STATUS hands-on asia-northeast1-a 1.9.7-gke.3 35.200.90.71 g1-small 1.9.7-gke.3 1 RUNNING
やっぱり最新のバージョンを使いたいので、作ったクラスタのバージョンをlatest
にしてみる。
gcloud container get-server-config
で指定できるバージョンの一覧を確認。
$ gcloud container get-server-config --zone asia-northeast1-a # Note that there is `defaultClusterVersion`
--cluster-version=latest
で、最新版にアップグレード。
$ gcloud container clusters upgrade hands-on --master --cluster-version=latest $ gcloud container clusters upgrade hands-on # Upgrade nodes following master's version $ gcloud container clusters list NAME LOCATION MASTER_VERSION MASTER_IP MACHINE_TYPE NODE_VERSION NUM_NODES STATUS hands-on asia-northeast1-a 1.10.5-gke.0 35.200.90.71 g1-small 1.10.5-gke.0 1 RUNNING
その他、
- nodeはmasterのバージョンを越えることができないので、masterのバージョンアップから先に行う必要がある
- この手動アップグレードを行なった後のmasterとnodeの自動アップグレードの基準がわからない。常に最新?自動更新してくれなくなる?(TODO: 確認)
- masterは一度バージョンを上げるとダウングレードできない。nodeはダウングレードできる。
- バージョンアップ時にNodeが一つずつ削除→再作成されるので、
hostPath
とemptyDir
にあるデータは消える。残したいデータはpersistent diskに退避する(TODO: 後で試す)。
Ref. Upgrading a cluster | Kubernetes Engine Documentation | Google Cloud
Ref. Versioning and upgrades | Kubernetes Engine Documentation | Google Cloud
Get and List Operations for Google Kubernetes Engine Clusters
ここまでやってきたGKEへの操作履歴を確認できる。statusの確認やまだbetaだけどcancelもできるっぽい。
$ gcloud container operations list $ gcloud container operations describe [OPERATION_ID]
Ref. Upgrading a cluster | Kubernetes Engine Documentation | Google Cloud
Delete Created k8s Cluster
不要になったクラスタはさっさと削除して節約する。
$ gcloud container clusters delete hands-on The following clusters will be deleted. - [hands-on] in [asia-northeast1-a] Do you want to continue (Y/n)? Deleting cluster hands-on...done. Deleted [https://container.googleapis.com/v1/projects/<your project name>/zones/asia-northeast1-a/clusters/hands-on].
kubectl
with GKE
ここからやっとkubectl
のconfigを触る。
ちなみに、公式のチートシートがある。
Ref. kubectl Cheat Sheet - Kubernetes
How to Switch Current Context
GKE上にk8sクラスタを作った直後はcurrent-context
が作ったクラスタのcontextに切り替わっている。
$ kubectl config current-context gke_[your project name]_asia-northeast1-a_hands-on
例えば、ローカルのdocker-for-desktopにcontextを切り替えてみる。
$ kubectl config current-context gke_[your project name]_asia-northeast1-a_hands-on $ kubectl config get-contexts CURRENT NAME CLUSTER AUTHINFO NAMESPACE docker-for-desktop docker-for-desktop-cluster docker-for-desktop staging * gke_[your project name]_asia-northeast1-a_hands-on gke_[your project name]_asia-northeast1-a_hands-on gke_[your project name]_asia-northeast1-a_hands-on minikube minikube minikube $ kubectl config use-context docker-for-desktop Switched to context "docker-for-desktop". $ kubectl config current-context docker-for-desktop
How to switch namespace with kubectl
使っているcontextが複数のnamespacesを持つ場合、以下の方法でnamespaceを切り替える。覚えれば良いとは言え少し煩雑。後述のkubensの方がシンプル。
$ kubectl get namespaces $ kubectl config set-context $(kubectl config current-context) --namespace=staging Context "docker-for-desktop" modified. $ kubectl config view | grep namespace: namespace: staging
How to get credentials from an existing kubernetes cluster
すでに稼働しているGKE上のクラスタへの操作を始めたい場合は、まずgcloud container get-credentials
でkubectlコマンドにクラスタ認識させる必要がある。
config(account
/project
/region
/zone
)が全て正しくないとcredentialsを取ることができないので注意する。
$ gcloud auth list $ gcloud config list $ gcloud container clusters list $ gcloud container clusters get-credentials [culster name]
get-credentials
を実行した時点でcontextが切り替わる。以降は、別のcontextに切り替えてもuse-context
で戻ってこれる。ちなみにuse-context
はタブ補完が効く。kubectlもgcloudもタブ補完周りは本当に気が利いていると思う。
$ kubectl config get-contexts $ kubectl config use-context [context name] $ kubectl cluster-info
get-credentials
で取ってきたaccess-token等の情報は~/.kube/config
に格納される。
kubectlが認識済みのcontextはconfig view
で一覧できる。
$ kubectl config view
Packages for Contexts
kubectlでは今どのcontextを使っているかが重要なので、どのアカウントのどのクラスタに向かってコマンドを叩いているのかを常に把握しておきたい、なんて考えていたらtwitterのタイムラインに丁度良いツイートが流れていた。
Looking for ways to enhance #kubectl? These tools work great together 👍🏼
— Kubernetes (@kubernetesio) 2018年3月1日
[1] https://t.co/5EGKQsZEq7 via @ahmetb
[2] https://t.co/QIPd0s5VOO via @jpmosco pic.twitter.com/e02R3vWq4p
kube-ps1
kube-ps1
はプロンプトに現在のcontextとnamespaceを表示する。(zshなら)以下ですぐに試せる。
brew install kube-ps1 $ wget https://raw.githubusercontent.com/jonmosco/kube-ps1/master/kube-ps1.sh -O /usr/local/bin/kube-ps1.sh $ source /usr/local/bin/kube-ps1.sh; export PROMPT="$(kube_ps1) $PROMPT"
自分は気に入ったので.zshrc
に仕込んだ。
自分の環境(oh-my-zsh)では一つ問題があって、kube<Tab>
と打った時に、不必要な環境変数がたくさん出るようになった。消したい。
ちなみに、kubeon
/kubeoff
で表示のon/offもできる。
$ kubeon $ kubeoff
bash用の設定方法やカスタマイズ方法はREADMEにある。
Ref. GitHub - jonmosco/kube-ps1: Kubernetes prompt info for bash and zsh
kubectx
/ kubens
kubectl config use-context
でcontextを切り替えたり、kubectlでnamespace切り替える代わりにkubectx
やkubens
も使える。
brew install kubectx
$ kubectx # List up all contexts
$ kubectx docker-for-desktop
$ kubectx -
$ kubens # List up all namespaces
$ kubens staging
$ kubens -
-
でどちらも一つ前のcontextやnamespaceに戻れる。
Ref. GitHub - ahmetb/kubectx: Switch faster between clusters and namespaces in kubectl
How to Authenticate Service Account
Googleアカウントでauthする他に、service accountでauthすることもできる。 GoogleアカウントがAWSで言う所のIAM Userでservice accountがIAM Role?service accountは基本IAM Role的にNode(Pod)に紐づけるもの?サービス毎に権限を絞ったservice accountで安全に作業した場合はこれをローカルでも使う?等々、まだあんまり触れていないので色々疑問が残っている(要確認)。
手順に従って、鍵が入ったファイルをダウンロードしてきてからactivateする。
$ gcloud iam service-accounts keys create \ --iam-account my-iam-account@somedomain.com key.json $ gcloud auth activate-service-account --key-file='./key.json' $ gcloud auth list $ gcloud auth describe [service account name]
Ref. Authorizing Cloud SDK tools | Cloud SDK Documentation | Google Cloud
How to Check User/Service Account Permissions
現在使っているアカウント(user
or service account
)にはどのようなロールが割り当てられており、ロールがどのような権限を持っているかを確認する。project単位でアカウントのロールの一覧を見ることができる(指定したuser
/service account
に紐付くロールだけを一覧するやり方がわからない!!)。
$ gcloud projects get-iam-policy [your project name] ...... - members: - user:[your gmail address] role: roles/owner ......
そこから確かめたいuserなりservice accountに紐付くroleの権限を以下で確認する。
$ gcloud iam roles describe roles/owner
Ref. Understanding roles | Cloud IAM Documentation | Google Cloud
Make sure gs object's ACL
余談になるが、権限周りで、もう一つ。クラウドストレージでスタティックWebページをホスティングする場合、オブジェクトのACLの設定を適切に設定しておかないといけない。 ドキュメントにあるように、htmlファイルをアップロードした後に、aclにAllUsersの権限を追加する。
gsutil acl ch -u AllUsers:R gs://www.example.com/index.html
ここで言いたいのは、設定した権限の確認方法。gsutil ls -L
でオブジェクトに設定されているACLを確認する。gsutil cp
はデフォルトだとアップロードした人にしか見えなくなるようにACLを上書きしてしまう。
$ gsutil ls -L gs://bucket/obj1
対処方法含めてACLについてはhelpとドキュメントを参照。
$ gsutil help acl
Ref. https://cloud.google.com/storage/docs/hosting-static-website:acl
etc...
その他、自分の必要に応じて随時更新。