Metadata-Version: 2.4
Name: fufu-cloud-cli
Version: 0.7.0
Summary: FUFU Cloud CLI for tenant-scoped mock cloud development and deployment
License-Expression: LicenseRef-Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML==6.0.3
Provides-Extra: yaml
Requires-Dist: PyYAML==6.0.3; extra == "yaml"
Dynamic: license-file

# FUFU Cloud CLI

以四個指令操作 FUFU Cloud 的租戶隔離開發環境：`fufu`、`aws-fufu`、
`gcloud-fufu`、`az-fufu`。這是 AWS、Google Cloud 與 Azure 的**明確子集**，
只供 FUFU mock 環境使用；不會把部署轉送到正式雲端。

## 安裝

需要 Python 3.10 以上。Python 套件預設包含 YAML 相依套件：

```bash
pip install fufu-cloud-cli
fufu --version
```

npm 版本需要 Node.js 18 以上，以及已安裝的 Python 3.10 以上；四個入口
呼叫相同的 Python CLI。npm 包內附純 Python YAML parser，沒有安裝腳本，
不會自行下載 Python 或執行 pip。

```bash
npm install fufu-cloud-cli
npx --no-install fufu --version
npx --no-install aws-fufu --help
```

全域安裝可使用 `npm install -g fufu-cloud-cli`。預設 Python 指令為 `python3`；
若名稱不同，將 `FUFU_PYTHON` 設成可信 Python 執行檔的路徑。
本機 Docker backend 只支援 Linux 與本機 Unix socket。API backend
不需要安裝 Docker；其他作業系統仍須另外驗證其 Python 與網路環境。

## 憑證與 CI

向 FUFU Cloud 管理者取得該租戶、該 provider 的專用 credential JSON。
CLI 不附預設帳號、共用金鑰或可用的租戶憑證，也不讀取 `.env`、瀏覽器
Cookie 或正式雲端登入工作階段。

在 CI 的秘密管理功能中注入 credential 檔案，並設定：

```bash
export FUFU_BACKEND=api
export FUFU_AWS_CREDENTIAL_FILE=/run/secrets/fufu-aws.json
export FUFU_GCP_CREDENTIAL_FILE=/run/secrets/fufu-gcp.json
export FUFU_AZURE_CREDENTIAL_FILE=/run/secrets/fufu-azure.json

fufu auth whoami --provider aws
aws-fufu sts get-caller-identity
gcloud-fufu auth list
az-fufu account show
```

credential 內含 FUFU endpoint。`FUFU_ENDPOINT` 可明確覆寫目的地：僅限
你信任且獲授權接收 credential 的 FUFU 服務。正式網路需使用 HTTPS；
只有 loopback 允許 HTTP。TLS 憑證驗證保持開啟，不跟隨重新導向，
不繼承系統 HTTP proxy。

一般命令交換短期權杖並在結束時嘗試撤銷。`fufu auth assume-role`
可建立受限 session 檔，檔案以排他方式建立且權限為 `0600`；請勿提交。
FUFU credential 與 session 檔仍屬秘密，必須由作業系統和 CI 控制存取。
原生雲端的 GitHub auth actions、OIDC 和 OAuth 不直接相容。
Lambda Function URL 的 AWS_IAM 支援長效 FUFU access key 的 SigV4 header signing；管理 API 仍使用 FUFU token。

## 部署與支援範圍

```bash
fufu capabilities
fufu capabilities --remote --provider gcp --require cloud-run-http
gcloud-fufu run deploy example --image approved-image:tag
gcloud-fufu run deploy example --source ./prepared-asgi.zip --entry-point main:app
gcloud-fufu functions deploy example-function --gen2 \
  --runtime python312 --source ./function --entry-point handler --trigger-http
aws-fufu lambda list-functions
```

自訂映像需先由 FUFU 管理者準備及核准。API 模式的 Cloud Run `--source`
接受已封裝 Uvicorn 與相依套件的 Python 3.12 ASGI ZIP／乾淨目錄，自動離線建置、
檢查映像並核准到目前租戶；不需要主機 SSH 或每次人工核准。
`--entry-point module:app` 是 FUFU 擴充旗標，預設 `main:app`。
來源上限為 ZIP 6 MiB、解壓縮 32 MiB、2000 個檔案；不接受隱藏檔、Dockerfile、
自訂安裝設定或非空 requirements.txt。相依套件需在 CI 封裝，服務端不執行安裝 hook。
這是固定 ASGI 配方，不提供完整 Cloud Build 或 registry API。
成功回應包含 `build.status`、`imageDigest` 與來源包雜湊；自動核准映像
僅供該租戶目前服務使用，取代或刪除最後一個引用後不再開放重用。

Function 來源會上傳指定目錄中的
Python 與 requirements 檔；Lambda 會上傳指定的 ZIP。請使用只含必要程式碼的
目錄或 ZIP，先移除硬編碼秘密、個人資料與不需要的檔案。
CLI 無法判斷任意原始碼或 ZIP 內的資料是否可以分享。

| 服務 | 可用範圍與主要限制 |
| --- | --- |
| Cloud Run | 已核准 HTTP 容器或 API 自動建置 Python ASGI 來源；支援配置後的 HTTPS 入口、Invoker policy；無 autoscaling、traffic splitting、Jobs |
| Cloud Run functions / Functions Gen 1 | Python 3.12 HTTP 函式；Gen 1 為相同 HTTP runtime 的模擬子集，無背景事件 |
| AWS Lambda | Python 3.10 / 3.12 ZIP、同步 invoke、程式碼更新、BUFFERED Function URL；遠端 ZIP 上限 6 MiB |
| GCS / S3 | bucket 與 object 操作子集；單一 object 上限 6 MiB，無 versioning / signed URL |
| DynamoDB / SQS / SSM | 明列資料操作；無完整交易、Streams、FIFO 或 KMS / SecureString |
| AWS IAM / GCP IAM | 租戶內 role / service account / policy 子集；default deny、限定 session；無原生雲端全量 IAM 語義 |
| API Gateway / Serverless profile | 簡化 HTTP Lambda proxy 和明確來源清單；不執行 plugins / CloudFormation |
| Azure | account 與資源群組目錄；尚無 Azure Functions 或其他 Azure runtime |
| EC2 / ECS / App Engine 等 | 部分只有 mock 目錄；不能視為執行中的 VM、Task 或應用 |

`fufu capabilities` 是隨版支援清單；`--remote` 另外查詢服務端能力。
`implemented` 代表明列子集已接入，`partial`、`mock-only`、`unsupported`
均不代表完整服務可用。未支援命令、旗標、YAML 欄位會拒絕，CI 應檢查退出碼。

## YAML / JSON

Cloud Run manifest 支援 `serving.knative.dev/v1`、`kind: Service`、
`metadata.name`、單一 container 的 image / port / env，以及明列的 service account。
服務 metadata.annotations 支援 `run.googleapis.com/ingress`（all／internal）與
`run.googleapis.com/invoker-iam-disabled`（字串 true／false）。
`fufu plan --file service.yaml` 可在不部署的情況下檢查設定；plan 僅列出環境變數名稱。
相同設定可用 JSON。其他正式雲端欄位需要顯式調整，不能宣稱所有設定無痛相容。

## 隱私與執行邊界

0.7.0 新增服務公開存取。需由平台配置 DNS、HTTPS 入口與 WAF 放行，
`publicAccess.status=ready` 表示入口已配置；仍應由 CI 實際 HTTP 呼叫確認外部可達。

```bash
gcloud-fufu run services update example --allow-unauthenticated --ingress all
gcloud-fufu run services get-iam-policy example
gcloud-fufu run services update example --no-allow-unauthenticated
gcloud-fufu auth print-identity-token --audiences https://app-SERVICE_ID.example.com
aws-fufu lambda create-function-url-config --function-name example --auth-type AWS_IAM
aws-fufu lambda get-function-url-config --function-name example
```

UI 與 CLI 共用同一份服務政策。Cloud Run 與 HTTP Functions 的匿名政策使用
`allUsers` 與對應 Invoker 角色。Lambda `NONE` 必須另加 `lambda:InvokeFunctionUrl`
（`--function-url-auth-type NONE`）和 `lambda:InvokeFunction`
（`--invoked-via-function-url`）兩項資源權限；只設定 NONE 不會自動開放呼叫。
入口支援有界限的普通 HTTP：請求與回應各 6 MiB、執行 15 秒，每服務每分鐘 120 次。
不支援 SSE、WebSocket、串流、STS 暫時金鑰、presigned URL 或真實 VPC。
GCP ID token 由 FUFU 的 RS256 issuer 簽發，綁定精確 audience，15 分鐘後過期；不接受 Google ID token。
`print-identity-token` 明確輸出秘密，應直接放入受控變數，避免 CI 日誌或 shell tracing。

- 套件沒有遙測、廣告、背景更新或安裝時網路腳本。
- API 請求只使用明確提供的 FUFU endpoint 和 credential；不掃描使用者家目錄。
- `whoami` 會輸出目前租戶、provider 與 scope；查詢／invoke 會輸出所要求的資料。
  請將 CI 日誌視為可能包含應用資料，不把敏感查詢結果公開。
- 本機部署會操作 Docker。明確執行 runtime prepare 或 function build 時，
  可能下載固定映像或安裝應用 requirements；不可信 requirements 仍可執行建置程式。
- FUFU 服務端的租戶隔離、IAM、日誌保存與資料保護由服務端負責。
  CLI 的本機檢查不等於對任何遠端部署作永久安全保證。

本套件目前保留著作權，未授予開源授權。套件公開可下載與原始碼採用開源授權
是不同事項；第三方 YAML parser 依其 MIT 授權散布。
