Skip to content
usacloud🐰 : CLI client for the Sakura Cloud🌸☁️
Go Other
  1. Go 99.1%
  2. Other 0.9%
Branch: master
Clone or download

README.md

Usacloud

usacloud_logo_h.png

usacloudさくらのクラウド用のCLIクライアントです。

Build Status Build status Slack

(English version)

主な特徴

  • さくらのクラウドの最新機能に追随。請求情報やオブジェクトストレージ、ウェブアクセラレータなども対応済み
  • クロスプラットフォーム(Windows/macOS/Linux)サポート。ARMでも動作可能。
  • Go言語で実装されたシングルバイナリ、インストールはバイナリをコピーするだけ(yum/apt/brewもサポート)
  • SSH/SCP/SFTP/VNCなどをバイナリ単体でサポート

使い方

オンラインで試す

ブラウザ上でUsacloudをお試しいただけます。

https://sandbox.usacloud.jp

ローカルマシンにインストール

macOS(brew) / Linux(apt or yum or brew) / bash on Windows(Ubuntu)

curl -fsSL https://releases.usacloud.jp/usacloud/repos/install.sh | bash

Windows(chocolatey)

choco install usacloud

chocolateyのusacloudパッケージは @223n さんによってメンテナンスされています。

Windows(chocolatey以外) / その他環境の場合

以下のリンクからバイナリーファイルをダウンロードして展開し、任意のフォルダー内に配置してください。
(PATHを通しておくと便利です)

bash_completionが利用できる場合は、以下のコマンドでusacloud用のbash_completionを導入することが出来ます。

curl -s -L https://releases.usacloud.jp/usacloud/contrib/completion/bash/usacloud >> ~/.bashrc

※bash_completionを有効化するには上記コマンドを実行後に再ログインしてください。

初期設定

usacloud config コマンドを用いてAPIキーを設定しておきます。 (APIキーの設定は~/.usacloud/<profile_name>/config.jsonにファイルとして保存されます。)

    $ usacloud config

    Setting SakuraCloud API Token => 
    	Enter token: [ENTER YOUR_API_TOKEN]

    Setting SakuraCloud API Secret => 
    	Enter secret: [ENTER YOUR_API_SECRET]
    	
    Setting SakuraCloud Zone => 
    	Enter zone[is1a/is1b/tk1a/tk1v](default:tk1a): [ENTER ZONE]
    	
    Setting Default Output Type => 
	    Enter default-output-type[table/json/yaml/csv/tsv]: 
   
    Written your settings to ~/.usacloud/default/config.json

APIキーの設定はusacloud config --showコマンドで確認可能です。

   $ usacloud config show
   
   token  = [YOUR_API_TOKEN]
   secret = [YOUR_API_SECRET]
   zone   = [YOUR_ZONE]
   

Note: APIキーは環境変数を用いて設定することも可能です。

   $ export SAKURACLOUD_ACCESS_TOKEN=[YOUR_API_TOKEN]
   $ export SAKURACLOUD_ACCESS_TOKEN_SECRET=[YOUR_API_SECRET]
   $ export SAKURACLOUD_ZONE=tk1v

詳細はUsacloudドキュメントを参照してください。

使い方

Usacloudドキュメント:基本的な使い方を参照してください。

NAME:
   usacloud - CLI client for SakuraCloud

USAGE:
   usacloud [global options] resource command [command options] [arguments...]

VERSION:
   NN.NN.NN, build xxxxxx

COMMANDS:
   config, profile                            A manage command of APIKey settings
   auth-status                                A manage commands of AuthStatus
   private-host                               A manage commands of PrivateHost
   server                                     A manage commands of Server
   archive                                    A manage commands of Archive
   auto-backup                                A manage commands of AutoBackup
   disk                                       A manage commands of Disk
   iso-image                                  A manage commands of ISOImage
   bridge                                     A manage commands of Bridge
   interface                                  A manage commands of Interface
   internet                                   A manage commands of Internet
   ipv4                                       A manage commands of IPv4
   ipv6                                       A manage commands of IPv6
   packet-filter                              A manage commands of PacketFilter
   switch                                     A manage commands of Switch
   database                                   A manage commands of Database
   load-balancer                              A manage commands of LoadBalancer
   mobile-gateway, mgw                        A manage commands of MobileGateway
   nfs                                        A manage commands of NFS
   vpc-router                                 A manage commands of VPCRouter
   dns                                        A manage commands of DNS
   gslb                                       A manage commands of GSLB
   proxy-lb, enhanced-load-balancer, proxylb  A manage commands of ProxyLB
   sim                                        A manage commands of SIM
   simple-monitor                             A manage commands of SimpleMonitor
   icon                                       A manage commands of Icon
   license                                    A manage commands of License
   ssh-key                                    A manage commands of SSHKey
   startup-script, note                       A manage commands of StartupScript
   bill                                       A manage commands of Bill
   coupon                                     A manage commands of Coupon
   object-storage, ojs                        A manage commands of ObjectStorage
   self                                       Show self info
   web-accel                                  A manage commands of WebAccel
   price, public-price                        A manage commands of Price
   product-disk, disk-plan                    A manage commands of ProductDisk
   product-internet, internet-plan            A manage commands of ProductInternet
   product-license, license-info              A manage commands of ProductLicense
   product-server, server-plan                A manage commands of ProductServer
   region                                     A manage commands of Region
   zone                                       A manage commands of Zone
   summary                                    Show summary of resource usage

GLOBAL OPTIONS:
   --token value                    API Token of SakuraCloud (default: none) [$SAKURACLOUD_ACCESS_TOKEN]
   --secret value                   API Secret of SakuraCloud (default: none) [$SAKURACLOUD_ACCESS_TOKEN_SECRET]
   --zone value                     Target zone of SakuraCloud (default: tk1a) [$SAKURACLOUD_ZONE]
   --config value, --profile value  Config(Profile) name [$USACLOUD_PROFILE]
   --timeout value                  Number of timeout minutes for polling functions (default: 20) [$SAKURACLOUD_TIMEOUT]
   --accept-language value          Accept-Language Header [$SAKURACLOUD_ACCEPT_LANGUAGE]
   --retry-max value                Number of API-Client retries (default: 0) [$SAKURACLOUD_RETRY_MAX]
   --retry-interval value           API client retry interval seconds (default: 0) [$SAKURACLOUD_RETRY_INTERVAL]
   --api-request-timeout value      Maximum wait time(seconds) for calling SakuraCloud API (default: 0) [$SAKURACLOUD_API_REQUEST_TIMEOUT]
   --no-color                       Flag of not using ANSI color output (default: false) [$NO_COLOR]
   --help, -h                       show help (default: false)
   --version, -v                    print the version (default: false)

COPYRIGHT:
   Copyright (C) 2017-2020 Kazumichi Yamamoto.

Examples: 一覧表示/検索

    # 全件表示
    $ usacloud switch ls 
   
    # 名称に"example"を含むものを一覧表示
    $ usacloud switch ls --name example
    
    # ソート条件指定(名称での昇順、IDでの降順)
    $ usacloud switch ls --sort Name --sort -ID
    
    # Limit/Offset指定(最大5件、2件目から表示)
    $ usacloud switch ls --max 5 --from 2
    

Examples: CRUD操作

    # 作成(Create)
    $ usacloud switch create --name "Example" --desc "description" --tags "Tag1" --tags "Tag2"
     
    # 詳細表示(Read)
    $ usacloud switch read <ID または 名称>
   
    # 更新(Update)
    $ usacloud switch update --name "Example-update" <ID または 名称>
    
    # 削除(Delete)
    $ usacloud switch delete <ID または 名称> 
    

Examples: サーバ作成

    # CentOSインストール済みのサーバを構築
    $ usacloud server build \
             --name server01 \               # サーバ名
             --os-type centos \              # OS種別(パブリックアーカイブを指定)
             --hostname server01 \           # ホスト名
             --password "$YOUR_PASSWORD" \   # 管理者パスワード
             --ssh-key-mode generate \       # SSH公開鍵(クラウド上で生成する)
             --disable-pw-auth               # SSH接続時のパスワード、チャレンジ/レスポンス認証の無効化

    # generated private-key is saved to ~/.ssh/sacloud_pkey_[ServerID]

Examples: サーバ操作(電源周り)

    # 起動
    $ usacloud server boot <ID または 名称> 
    
    # シャットダウン(graceful)
    $ usacloud server shutdown <ID または 名称> 
    
    # シャットダウン(force)
    $ usacloud server shutdown-force <ID または 名称> 
    
    # リセット(hard)
    $ usacloud server reset <ID または 名称> 
    

Examples: サーバへの接続(SSH/SCP/VNC/リモートデスクトップ)

    # サーバへのSSH接続
    # デフォルトでは~/.ssh/sacloud_pkey_[サーバID]ファイルが存在すれば秘密鍵として利用する(-iオプションで明示も可)
    $ usacloud server ssh <ID または 名称> 
    
    # サーバにSSH接続し、任意のコマンドを実行(Windowsコマンドプロンプトからでも実行可能)
    $ usacloud server ssh-exec <ID または 名称>  cat /etc/passwd
    
    # SCPでのアップロード/ダウンロード
    $ usacloud server scp local-file.txt [ID または 名称]:/home/ubuntu/remote-file.txt # ローカルからリモートへ
    $ usacloud server scp [ID または 名称]:/home/ubuntu/remote-file.txt local-file.txt # リモートからローカルへ
    $ usacloud server scp -r local-dir [ID または 名称]:/home/ubuntu/remote-dir        # ディレクトリに対して再帰的に処理
   
    # OSのデフォルトVNCクライアントを用いてサーバへVNC接続
    # (Windowsの場合、.vnc拡張子に適切なVNCクライアントを関連付けしておく必要あり)
    $ usacloud server vnc <ID または 名称> 

    # OSのデフォルトRDPクライアントを用いてサーバへリモートデスクトップ接続
    $ usacloud server remote-desktop <ID または 名称>
    # または
    $ usacloud server rdp <ID または 名称>

Examples: FTPSでのアップロード/ダウンロード(アーカイブ/ISOイメージ)

    # ISOイメージのアップロード
    $ usacloud iso-image create --name example --iso-file example.iso
    
    # アーカイブのダウンロード(マイアーカイブのみダウンロード可能)
    $ usacloud archive download --file-destination example.img <ID または 名称> 
    

Examples: 請求関連

    # 請求情報一覧
    $ usacloud bill list
    
    # 請求CSVの出力
    $ usacloud bill csv [BillID]

Examples: オブジェクトストレージの操作

    # オブジェクトストレージ用にAPIキー設定(バケットごと)
    $ export SACLOUD_OJS_ACCESS_KEY_ID="[YOUR_BUCKET_ACCESS_KEY]"
    $ export SACLOUD_OJS_SECRET_ACCESS_KEY="[YOUR_BUCKET_SECRET_KEY]"
    
    # オブジェクト一覧表示
    $ usacloud object-storage ls 
    $ usacloud object-storage ls dir1/dir2

    # オブジェクトのダウンロード
    $ usacloud object-storage get remote.txt           # 標準出力へ
    $ usacloud object-storage get remote.txt local.txt # ローカルファイルへ
    $ usacloud object-storage get -r remote/ local/    # ディレクトリを再帰的に処理

    # オブジェクトのアップロード
    $ usacloud object-storage put local.txt remote.txt 
    $ usacloud object-storage put local.txt dir1/dir2/remote.txt
    $ usacloud object-storage put -r local/ remote/    # ディレクトリを再帰的に処理
    
    # オブジェクトの削除
    $ usacloud object-storage del remote.txt
    $ usacloud object-storage del -r remote/           # ディレクトリを再帰的に処理

Examples: ウェブアクセラレータ

    # ウェブアクセラレータ上のキャッシュを削除
    $ usacloud web-accel purge https://example.com https://foobar.com

Examples: 出力の定義

    # テーブル形式(デフォルト)
    $ usacloud switch ls

    # JSON形式
    $ usacloud switch ls --output-type json

    # YAML形式
    $ usacloud switch ls --output-type yaml
     
    # CSV/TSV形式
    $ usacloud switch ls --output-type csv # or tsv

    # 出力する列を指定(CSV/TSV形式での出力時に指定可能)
    $ usacloud switch ls --output-type tsv --col ID --col Name
   
    # IDまたはキーのみ出力
    $ usacloud swtich ls -q # or --quiet
    
    # golangのテンプレートを用いてカスタム出力
    $ usacloud switch ls --format "ID is '{{.ID}}', Name is '{{.Name}}'"
    ID is '123456789012', Name is 'example'

Examples: 出力の定義(モニタリングツール用)

    # target resource ID = 123456789012

    # for munin
    $ usacloud internet monitor --format "target.value {{.In}}" 123456789012
    
    # for zabbix_sender(zabbix_hostname=router01 , item_key=packet.in)
    $ usacloud internet monitor --format "router01 packet.in {{.UnixTime}} {{.In}}" 123456789012 \
         | zabbix_sender -z your.zabbix.hostname -p 10051 -T -i -
    
    # for sensu/mackerel
    $ OUTPUT_FORMAT=`echo -e "{{.Key}}\t{{.In}}\t{{.UnixTime}}"`
    $ usacloud internet monitor --format "$OUTPUT_FORMAT" 123456789012

Examples: 複数のAPIキーの利用(プロファイル機能)

    # 一覧
    $ usacloud config list

    # プロファイルの作成(対話形式)
    $ usacloud config edit your-profile-name1

    # プロファイルの作成(非対話形式)
    $ usacloud config edit --zone "is1a" --token "token" --secret "secret" your-profile-name1
    
    # プロファイル内容の表示
    $ usacloud config show your-profile-name1

    #現在選択中のプロファイル名表示
    $ usacloud config current

    #プロファイル切り替え
    $ usacloud config use your-profile-name1

    #プロファイルの削除
    $ usacloud config delete your-profile-name1

開発

ビルド

$ make build

ビルド(Docker上でのビルド/クロスプラットフォーム向けビルド)

$ make docker-build

テスト

$ make test

統合テスト

統合テストの実行には以下の環境変数の設定が必要です。

  • SAKURACLOUD_ACCESS_TOKEN
  • SAKURACLOUD_ACCESS_TOKEN_SECRET
  • SAKURACLOUD_ZONE
# ローカルマシン上で実行する場合(bats/jqが必要)
$ make integration-test
# 個別のテストだけ実行したい場合(ディレクトリ単位、またはファイル単位でも可)
$ test/integration/run_bats.sh test/integration/bats/対象ディレクトリor対象ファイル名

# Docker上で実行する場合(bats/jq不要)
$ make docker-integration-test    

テストを追加したい場合はtest/integration/README.mdを参照してください。

各コマンドのソース生成

$ make gen
$ # or
$ make gen-force

新しいリソース/コマンドの追加

define配下に定義ファイルを作成しmake gen-forceコマンドでソース生成してください。

ドキュメント

ドキュメントはGithub Pagesを利用しています。(masterブランチのdocsディレクトリ配下)
静的ファイルの生成はmkdocsコマンドで行なっています。

ドキュメントのPRの際はbuild_docsディレクトリ配下のみ修正を行い、docsディレクトリ配下は変更しないでください。
docsディレクトリはリリース時に一括更新されます。

# ドキュメントのプレビュー用サーバー起動(http://localhost/でプレビュー可能)
make serve-docs

# ドキュメントの検証(textlint)
make lint-docs

License

usacloud Copyright (C) 2017-2020 The Usacloud Authors.

This project is published under Apache 2.0 License.

You can’t perform that action at this time.