:construction_worker: :point_right: 工作人員專用 :warning: 非請勿入。

{%hackmd @docsharedstyle/default %}

TWCC-CLI α

{%hackmd @tpl/draft_alert_zh %} {%hackmd @tpl/draft_alert_en %}

本文件為 TWCC-CLI v0.5 之使用手冊,詳細內容操作情境仍在持續更新。TWCC-CLI (Command Line Interface) 是 TWCC 的命令列工具。除了 TWCC 入口網站, TWCC-CLI 提供管理 TWCC 資源的另一種選擇!

以下提供如何安裝 TWCC-CLI、使用開發型容器服務(CCS, Container Computer Service)、虛擬運算服務(VCS, Virtual Computer Service)與雲端物件儲存服務(COS, Cloud Object Storage)的教學指南。

[TOC]

1. 部署操作環境

1-1. 於TWCC開啟開發型容器

請自TWCC使用者介面登入後開啟「開發型容器」,並參考 :point_right: 連線使用方式。 選擇 :point_right: SSH登入、或 :point_right: Jupyter Notebook Terminal,登入。

:::info :bulb: 若使用虛擬運算服務操作TWCC-CLI,請參考 :point_right: 於虛擬運算服務中操作TWCC-CLI :bulb: TWCC CCS/VCS Ubuntu 20.04版本內建TWCC-CLI,可略過安裝步驟, 前往1-3-進入-TWCC_CLI-環境並開始使用服務 :::

1-2. 安裝TWCC-CLI

  • 開啟Terminal,並安裝TWCC-CLI

pip install TWCC-CLI

:::warning :information_source: 關於twccli指令與用途

指令

用途

-ch

切換指定TWCC資源,適用於:VCS, VDS等

config

TWCC-CLI環境配置相關設定

cp

上傳、下載檔案功能,適用於:COS

ls

檢視指定TWCC資源資訊,適用於:CCS, COS, VCS, VDS等

mk

建立(調配)TWCC資源,適用於:CCS, COS, VCS, VDS等

net

網路設定相關操作,CCS, VCS

rm

刪除TWCC資源,適用於:CCS, COS, VCS, VDS等

詳細操作請參考-h , --help :::spoiler –help of config

  • twccli config --help

![](https://cos.twcc.ai/SYS-MANUAL/uploads/upload_9548b4ef631f10523848970cc03a0221.png =55%x)

:::

1-3. 進入 TWCC_CLI 環境並開始使用服務

  • 輸入您的TWCC用戶資訊:包含【TWCC API 金鑰】 與 【計畫編號】 (請至TWCC使用者頁面 -> API金鑰管理)

twccli config init
  • 輸入語言、及其他參數設定

export LANG=C.UTF-8
export LC_ALL=C.UTF-8
export PYTHONIOENCODING=UTF-8

:::info :bulb:查詢金鑰、計畫編號的方法:

  • 登入 TWCC 後,點選右上角的使用者名稱,再點選「API 金鑰管理」


  • 便可檢視、複製您的金鑰、計畫編號

  • 請記得==時常更新您的金鑰==,並且==避免使用主金鑰==、==主金鑰切勿外流==

:::

:::info

:bulb: 更換使用計畫:

rm -rf ~/.twcc_data

![](https://cos.twcc.ai/SYS-MANUAL/uploads/upload_acb61adc3c6c88a39afc53443805c6f6.png =80%x) :::

  • 確認用戶資訊、API金鑰、計畫編號正確

twccli config whoami

  • 確認TWCC-CLI版本資訊(欲確認目前最新版本,請洽 :point_right: TWCC-CLI github

twccli config version

1-4. TWCC_CLI 版本更新

  • 使用以下指令進行CLI版本更新

pip install -U TWCC-CLI

完成更新後,請重新確認使用者資訊

twccli config init

2. 開發型容器服務(CCS, Container Computer Service)

:::info :bulb: 注意:以 TWCC CLI 使用開發型容器服務,須先部署 TWCC CLI 的操作環境。參見本文件上方:1. 部署操作環境 :::

:::warning :information_source: 關於 CCS 指令與用途

指令

用於

用途

ls

ccs

檢視開發型容器資訊

mk

ccs

建立開發型容器

net

ccs

設定開發型容器網路服務

rm

ccs

刪除開發型容器

詳細操作請參考-h , --help

:::spoiler –help of CCS

  • twccli ls ccs --help ![](https://cos.twcc.ai/SYS-MANUAL/uploads/upload_4b48bac10c45dd38d3b5651a20ce1962.png =85%x)

  • twccli mk ccs --help ![](https://cos.twcc.ai/SYS-MANUAL/uploads/upload_112dccdb8f5a5022afe92cbcf7c81ffa.png =85%x)

  • twccli net ccs --help ![](https://cos.twcc.ai/SYS-MANUAL/uploads/upload_d7126b3e82d6f365c9e11630e705b030.png =80%x)

  • twccli rm ccs --help ![](https://cos.twcc.ai/SYS-MANUAL/uploads/upload_71f943929ca40c8815599de9b6b62c4d.png =80%x)

:::

2-1. 建立開發型容器

  • 以預設建立開發型容器

twccli mk ccs

:::info :bulb: 預設建立資訊:

映像檔類型、映像檔

容器名稱

硬體設定

TensorFlow (latest environment)

twcc-cli

1 GPU + 04 cores + 090GB memory

:::

  • 建立名為 clitest 的預設開發型容器

twccli mk ccs -n clitest

:::info :bulb: 注意:

  • 容器名稱命名條件:字母須為小寫字母或數字、首字母為小寫字母、長度6-16個字母

  • GPU 數量與其他資源的比例與定價請參考 :point_right: TWCC 價目表

  • TWCC 提供的映像檔類型、映像檔,可參考 :point_right: 2-3. 檢視所有容器規格 :::

2-2. 檢視容器資訊

  • 檢視容器建立狀況,或可由TWCC使用者介面上確認容器建立完成

twccli ls ccs

  • 檢視計劃下的所有容器 (僅限租戶管理員使用)

twccli ls ccs -all

2-3. 檢視所有容器規格

  • 檢視所有映像檔類型

twccli ls ccs -itype
  • 檢視所有映像檔規格

twccli ls ccs -img
  • 檢視所有映像檔gpu規格

twccli ls ccs -gpu

2-4. 建立指定容器環境

  • 檢視並確認欲建立之容器規格

  • 建立映像檔類型"Caffe2",映像檔規格為"caffe2-18.08-py3-v1:latest"、gpu數量 2 的容器,並命名 cusccs

twccli ls ccs -itype
twccli ls ccs -itype "Caffe2" -img
twccli ls ccs -gpu
twccli mk ccs -itype "Caffe2" -img "caffe2-18.08-py3-v1:latest" -gpu 2 -n cusccs

:::spoiler 操作範例截圖(點我)

:::

2-5. 檢視容器連線資訊

  • 檢視容器 ID 為 1249374 的容器jupiter notebook連線資訊(URL)

  • 以瀏覽器開啟URL,連線入jupyter notebook

twccli ls ccs -s 1249374 -gjpnb
  • 檢視容器 ID 為 1249380 的容器ssh連線資訊

  • 以ssh 連線

  • 確認連線

  • 輸入主機帳號密碼

twccli ls ccs -s 1249380 -gssh
ssh `連線資訊`
  • 若要離開連線,輸入exit

:::spoiler 操作範例截圖(點我)

![](https://cos.twcc.ai/SYS-MANUAL/uploads/upload_3c381b0a5da433a081b46cbd463701a4.png =65%x)

:::

2-6. 容器複本

  • TWCC CLI 提供使用者客製化容器,在 TWCC 完成環境部署後,可保存容器複本,再次建立容器便能快速進入熟悉的工作環境。

:::warning :information_source: 容器複本只能做一次!! :information_source: 關於 CCS 的容器副本操作指令與用途

指令

用於

參數

用途

mk

ccs

-dup -tag

建立副本申請

ls

ccs

-dup

檢視副本申請

詳細操作請參考-h , --help :::

2-6-1. 提出容器複本的申請

  • 提出申請保留容器 ID 為 934336 的容器,image tag 自訂為 dup1

twccli mk ccs -s 934336 -dup -tag dup1 

:::info :bulb: 使用者需先在 TWCC 建立容器,並自行將環境部署完成,才能提出此申請。 :::

2-6-2. 檢視已提出的申請狀態

twccli ls ccs -dup

2-6-3. 以複本建立客製化容器

  • 檢視並確認欲建立之容器規格

  • 建立"Custom Image"中,映像檔規格與tag為"tensorrt-19.08-py3:dup1"的容器,並命名 dupcli

twccli ls ccs -img "Custom Image"
twccli mk ccs -itype "Custom Image" -img "tensorrt-19.08-py3:dup1" -n dupcli

2-7 開啟與關閉對外服務埠

:::warning :information_source: 關於 CCS 設定對外服務埠指令與用途

指令

用於

用途

ls

ccs

檢視對外服務埠資訊

net

ccs

設定對外服務埠服務

詳細操作請參考-h , --help :::

  • 確認ID為886330容器的對外服務埠現有狀態

twccli ls ccs -p -s 886330
  • 為ID886330容器,開啟號碼為5000的對外服務埠

twccli net ccs -p 5000 -open -s 886330
  • 確認開啟對外服務埠狀態

twccli ls ccs -p -s 886330
  • 為ID886330的容器,關閉號碼為5000的對外服務埠

twccli net ccs -p 5000 -close -s 886330
  • 確認關閉對外服務埠狀態

twccli ls ccs -p -s 886330

:::spoiler 操作範例截圖(點我) :::

2-8. 刪除容器

  • 刪除 site_id 為 934369 的容器

  • 輸入command以檢視容器狀況,或可由TWCC使用者介面上確認容器刪除成功

twccli rm ccs -s 934369
twccli ls ccs

3. 虛擬運算服務(VCS, Virtual Computer Service)

:::info :bulb: 注意:以 TWCC CLI 使用虛擬運算服務,須先部署 TWCC CLI 的操作環境。參見本文件上方:1. 部署操作環境 :::

:::warning :information_source: 關於 VCS 指令與用途

指令

用於

用途

ls

vcs

檢視虛擬運算個體資訊

mk

vcs

建立虛擬運算個體

net

vcs

設定虛擬運算網路服務

rm

vcs

刪除虛擬運算個體

詳細操作請參考-h , --help :::spoiler –help of VCS

  • twccli ls vcs --help ![](https://cos.twcc.ai/SYS-MANUAL/uploads/upload_81afdf28977568cdd0564aeb4edec7c1.png =85%x)

  • twccli mk vcs --help ![](https://cos.twcc.ai/SYS-MANUAL/uploads/upload_91ca28b894edd993cef430a95c563545.png =85%x)

  • twccli net vcs --help ![](https://cos.twcc.ai/SYS-MANUAL/uploads/upload_f39c1dbbf2dd643c2bae60b03b401a98.png =85%x)

  • twccli rm vcs --help ![](https://cos.twcc.ai/SYS-MANUAL/uploads/upload_d0fea3b853232f163db8d34425960ef6.png =85%x)

:::

3-1. 鑰匙對

鑰匙對是登入虛擬運算個體的憑證,建立個體之前,必須先取得或建立鑰匙對才能使用個體功能。

3-1-1. 建立鑰匙對

  • 輸入command以建立名為key1的鑰匙對

twccli mk key -n key1

:::info :bulb: 為方便管理,建議為每項鑰匙對命名 :::

3-1-2. 檢視鑰匙對

  • 輸入command以確認鑰匙對建立狀況,或可由TWCC使用者介面上確認鑰匙對建立完成

twccli ls key

3-2. 建立虛擬運算個體

  • key1鑰匙對建立預設虛擬運算個體

twccli mk vcs -key key1

:::info :bulb: 預設建立資訊:

映像檔類型、映像檔

型號

網路資訊

硬體設定

Ubuntu 16.04

v.2xsuper

default_network

0 GPU + 8 CPU + 064GB memory

:::

  • key1鑰匙對建立名為 vcscli 的虛擬運算個體

twccli mk vcs -key key1 -n vcscli

:::info :bulb: 注意:

  • 虛擬運算個體名稱命名條件: 字母須為小寫字母或數字、首字母為小寫字母、長度6-16個字母

  • GPU 數量與其他資源的比例與定價請參考 :point_right: TWCC 價目表

  • TWCC 提供的映像檔類型、映像檔,可參考:point_right: 3-4. 檢視所有虛擬運算個體規格

:::

3-2-1. 為虛擬運算個體建立公用IP

  • 為ID937648虛擬運算個體,建立公用IP

  • 檢視是否建立成功

twccli net vcs -s 937648 -fip
twccli ls vcs

3-3. 檢視虛擬運算個體資訊

  • 檢視虛擬運算個體狀況,或可由TWCC使用者介面上確認虛擬運算個體建立完成

twccli ls vcs

:::info :bulb:使用cli建立的虛擬運算個體將不預設公用IP,欲設定公用IP請參考:point_right: 3-2-1. 為虛擬運算個體建立公用IP :::

  • 檢視計劃下的所有虛擬運算個體 (僅限租戶管理員使用)

twccli ls vcs -all

3-4. 檢視所有虛擬運算個體規格

  • 檢視所有映像檔規格

twccli ls vcs -img
  • 檢視所有映像檔產品型號與規格

twccli ls vcs -ptype

3-5. 建立客製化虛擬運算個體 :warning: (TBD..)

  • 檢視並確認欲建立之虛擬運算規格

  • 以客製規格建立虛擬運算個體 (後續將持續更新功能與使用範例..)

3-6. 虛擬運算個體快照 :warning: (TBD..)

  • TWCC CLI 提供使用者客製化虛擬運算個體,在 TWCC 完成環境部署後,可保存虛擬運算個體快照(建立快照),再次建立虛擬運算個體便能快速進入熟悉的工作環境。

:::warning :information_source: 關於 VCS 的個體快照操作指令與用途

指令

用於

參數

用途

mk

vcs

-snap

建立快照申請

ls

vcs

-snap

檢視快照申請

rm

vcs

-snap

移除快照

詳細操作請參考-h , --help :::

3-6-1. 提出虛擬運算個體快照的申請

  • 為 ID 為 918628 的虛擬運算個體建立快照

twccli mk vcs -s 918628 -snap

:::info :bulb: 使用者需先在 TWCC 建立虛擬運算個體,並自行將環境部署完成,才能提出此申請。 :::

3-6-2. 檢視已提出的申請狀態

  • 檢視為 ID 為 918628 的虛擬運算個體建立的快照狀態

twccli ls vcs -snap -s 918628  

3-6-3. 以快照建立虛擬運算個體 :warning: (TBD..)

(後續將持續更新功能與使用範例..)

3-6-4. 檢視全部快照資訊

  • 檢視使用者所有快照資訊

twccli ls vcs -snap
  • 檢視計畫下的所有快照資訊 (僅限租戶管理員使用)

twccli ls vcs -snap -all

3-6-5. 刪除快照

  • 刪除ID為115453的快照

twccli rm vcs -snap -snap-id 115453

3-6-6. 設定定時快照 :warning:

:::warning :warning: 本項功能目前僅能使用於『虛擬運算服務操作TWCC-CLI』

:bulb: 若需使用虛擬運算服務操作TWCC-CLI,詳見 :point_right: 於虛擬運算服務中操作TWCC-CLI :::

  • 使用 crontab -e 進行設定,相關使用功能請參照 CronHowTo

  • 指定任意時間進行快照工作,在此為範例為==午夜 01:01==。

3-7 安全性群組管理

:::warning :information_source: 關於 VCS 的安全性群組操作指令與用途

指令

用於

參數

用途

ls

vcs

-secg*必要 / -s*必要

查詢安全性群組

net

vcs

-secg*必要 / -s*必要

設定安全性群組

rm

vcs

-secg*必要 / -s*必要

移除安全性群組

詳細操作請參考-h , --help :::

針對您所建立的虛擬機可各別進行安全性群組管理,其功能即為 TWCC 提供的免費防火牆,可確保您的計算資源的存取來源或目的網路及服務埠均在控管的範圍。使用方試如下:

3-7-1 列出虛擬機現有安全性群組 (Security Group, secg)

  • 列出現有虛擬機安全性群組,可透過下列指令進行查詢:

twccli ls vcs # 列出現有虛擬機
twccli ls vcs -secg -s 937648 # 列出ID為937648虛擬機的安全性群組

3-7-2 設定安全性群組

:::info 若要進行設定網路安全性群組,請使用 twccli net vcs --help 進行查詢各細項功能 :::

  • 若要設定對安全網路段:==10.10.10.0/24==,開放 ==TCP:81== 埠的連入(ingress),使用指令如下,

twccli net vcs -secg -s 892486 -cidr 10.10.10.0/24 -in -proto tcp -p 81
twccli ls vcs -secg -s 892486

:::spoiler 操作範例截圖(點我) :::

3-7-2 移除安全性群組 :warning:

若要取消已設定的安全性群組,可使用 :point_right: twccli rm vcs -secg $SecurityGroupId

:::info :bulb: 刪除安全性群組的時候,請使用安全性群組的 UUID 進行刪除。 UUID 最短僅需提供==前8碼==,即可進行刪除。 ::: 參考範例:point_down::

twccli rm vcs -secg ff781775

(後續將持續更新功能與使用範例..)

3-8. 刪除虛擬運算個體與鑰匙對

3-8-1. 刪除虛擬運算個體

  • 刪除 site_id 為 937651 的虛擬運算個體

twccli rm vcs -s 937651
  • 輸入command以檢視虛擬運算個體狀況,或可由TWCC使用者介面上確認虛擬運算個體刪除成功

twccli ls vcs

3-8-2. 刪除鑰匙對

  • 刪除名稱為 key1 的鑰匙對

twccli rm key -n key1

:::info :bulb: 注意: 刪除後, 請自行刪除本機端鑰匙對 :::spoiler :::

  • 輸入command以檢視鑰匙對狀況,或可由TWCC使用者介面上確認虛擬運算個體刪除成功

twccli ls key

4. 雲端物件儲存服務(COS, Cloud Object Storage)

:::info :bulb: 注意:

  • 若在開發型容器內使用雲端物件儲存、存取資料,需先在容器環境內部署 TWCC CLI 工具。參見本文件上方:1. 部署操作環境

  • 一般檔案管理 (上傳/刪除/搜尋Metadata/設定通知),亦可於 TWCC 入口網站內操作,參見:雲端物件儲存 :::

:::warning :information_source: 關於 COS 指令與用途

指令

用於

用途

cp

cos

上傳、下載檔案至雲端儲存體

ls

cos

檢視雲端儲存體資訊

mk

cos

建立雲端儲存體

rm

cos

刪除雲端儲存體

詳細操作請參考-h , --help :::spoiler –help of COS

  • twccli cp cos --help ![](https://cos.twcc.ai/SYS-MANUAL/uploads/upload_d8f07b9dbf9217d1ffb6df2b78787953.png =85%x)

  • twccli ls cos --help ![](https://cos.twcc.ai/SYS-MANUAL/uploads/upload_623d7615781afa9cfc70734c20663b67.png =85%x)

  • twccli mk cos --help ![](https://cos.twcc.ai/SYS-MANUAL/uploads/upload_b26addeb3b5c79b2d7f17284e4ef45fd.png =55%x)

  • twccli rm cos --help ![](https://cos.twcc.ai/SYS-MANUAL/uploads/upload_78464b3af8041812c1ddfcb0a96fb2c7.png =85%x) :::

4-1. 建立儲存體

  • 建立名為 bk_cli 的儲存體

twccli mk cos -bkt clibkt

4-2. 檢視所有儲存體

twccli ls cos

4-3. 上傳檔案至儲存體

:::info :bulb: 上傳檔案可藉『相對路徑』、『絕對路徑』擷取資料傳入儲存體

:::

4-3-1. 上傳單一檔案 -sync to-cos

  • 自當前路徑上傳單一檔案(檔名:testfile1)

  • 並利用檢視指令確認檔案是否成功上傳目標儲存體clibkt

twccli cp cos -bkt clibkt -fn testfile1 -sync to-cos
twccli ls cos -bkt clibkt
  • 自相對路徑上傳單一檔案(檔名:test1)至目標儲存體testf1/目錄下

twccli cp cos -bkt clibkt -dir testf1/ -fn test1 -sync to-cos
  • 上傳相對路徑資料夾的所有檔案(資料夾:testf2) 至目標儲存體

twccli cp cos -bkt clibkt -dir testf2 -sync to-cos

4-4. 檢視儲存體的所有檔案

  • 檢視儲存體clibkt 中所有檔案資訊

twccli ls cos -bkt bk_cli

4-5. 下載儲存體檔案 或 整個儲存體 -sync from-cos

  • 自儲存體下載單一檔案(檔名:testfile1)至當前資料夾

  • 並檢視是否下載成功

twccli cp cos -bkt clibkt -okey testfile1 -sync from-cos
twccli ls cos -bkt clibkt

  • 下載整包儲存體至指定目錄

  • 並檢視是否下載成功

twccli cp cos -bkt clibkt -dir download/ -sync from-cos
twccli ls cos -bkt clibkt

4-6. 刪除儲存體資料

:::danger 這個操作會對您的資料完全刪除,請小心使用。 :::

  • 刪除儲存體 clibkttestfile2 檔案

twccli rm cos -bkt clibkt -okey testfile2

4-7. 刪除儲存體

:::info :bulb: 刪除儲存體前,請先檢視ls目標儲存體是否已清空資料 :point_right: null :::

  • 刪除「已清空」的儲存體 clibkt1

twccli ls cos -bkt clibkt1
twccli rm cos -bkt clibkt1

  • 刪除「未清空」的儲存體 clibkt

twccli ls cos -bkt clibkt
twccli rm cos -bkt clibkt -r

5. 虛擬網路 (Virtual Network)

:::warning :information_source: 關於 VNET 指令與用途

指令

用於

用途

ls

vnet

檢視虛擬網路資訊

mk

vnet

建立虛擬網路

rm

vnet

刪除虛擬網路

詳細操作請參考-h , --help :::spoiler –help of VNET

  • twccli ls vnet --help

  • twccli mk vnet --help

  • twccli rm vnet --help

:::

5-1. 建立虛擬網路

  • 以網段 172.16.0.0/24 及閘道 172.16.0.254 建立虛擬網路

twccli mk vnet -cidr 172.16.0.0/24 -gw 172.16.0.254

:::info :bulb: 注意:

  • 192.168.1.0/24 為系統保留的 CIDR,請不要使用。 :::

5-2. 檢視虛擬網路

  • 檢視所有虛擬網路

twccli ls vnet

  • 檢視特定虛擬網路261894詳細資訊

twccli ls vnet -id 261894

5-3. 刪除虛擬網路

  • 刪除虛擬網路261894

twccli rm vnet -id 261894

6. 虛擬磁碟服務(Virtual Disk Service)

:::warning :information_source: 關於 VDS 指令與用途

指令

用於

用途

ls

vds

檢視虛擬磁碟服務資訊

mk

vds

建立虛擬磁碟服務

rm

vds

刪除虛擬磁碟服務

|

詳細操作請參考-h , --help :::spoiler –help of VNET

  • twccli ls vnet --help

  • twccli mk vnet --help

  • twccli rm vnet --help

:::

6-1 建立虛擬磁碟服務

  • 以預設建立虛擬磁碟服務

twccli mk vds

:::info :bulb: 預設建立資訊:

虛擬磁碟服務類型

虛擬磁碟服務名稱

虛擬磁碟服務容量大小

HDD

twccli

100 GB

:::

  • 建立名為 clitest ,且指定儲存容量為10 GB的虛擬磁碟服務

twccli mk vds -n clitest -sz 10

6-2 檢視虛擬磁碟服務資訊

  • 檢視虛擬磁碟服務建立相關資訊

twccli ls vds

6-3 刪除虛擬磁碟服務

  • 刪除ID為376749的虛擬磁碟服務

twccli rm vds -id 376749

  • 強制(無警告視窗)刪除ID為376716的虛擬磁碟服務

twccli rm vds -id 376749 -f

Sup. 於虛擬運算 VCS 服務中操作TWCC-CLI

Sup-1. 開啟虛擬運算服務

Sup-2. 安裝TWCC-CLI

  • 連線成功後,更新與安裝套件工具(視情況選擇安裝python2或python3版本)

sudo apt update
sudo apt install python-pip #in python2
sudo apt install python3-pip #in python3
  • 安裝TWCC-CLI(請注意上一步pip套件之python版本)

pip install TWCC-CLI #in python2
pip3 install TWCC-CLI #in python3
  • 輸入設定指令,並確認是否安裝完成

twccli

Sup-3. 輸入您的TWCC-CLI用戶資訊

:::info

:information_source: 接續本文 :point_right: #1-3-進入-TWCC_CLI-環境並開始使用服務 :::