--- name: jump-api description: Create and manage jumps. A jump is a bastion used to access controlplane, dedicated, serverless, premium, and resourcepool clusters. --- # Key Concepts * `Jump`: indicates an access channel to a single cluster. * `Authorization`: indicates a request for one or more Jumps, and represents access permissions for multiple clusters. * `DestinationType`: the destination cluster type. Supported values: `controlplane`, `dedicated`, `serverless`, `byoc`, `premium`, `premium_resource_pool`. * `Privilege`: the requested privilege for an Authorization. Supported values: `read_only`, `read_write`, `admin`. * `Expiration`: the validity period of an Authorization. Supported values: `1h`, `3h`, `6h`, `12h`, `24h`, `3d`, `7d`, `30d` (`30d` is only for `controlplane`). * `Authorization Phase`: the status of an Authorization. Supported values: `approving`, `creating`, `created`, `expired`, `notapproved`, `canceled`. Jumps under an Authorization are only available when the phase is `created`. # Available Actions ## List Available Destinations List available destination IDs for a DestinationType. API Path: `/jump/destination/{destination_type}`. Method: `GET`. NOTE: This is only effective for DestinationType `controlplane` and `serverless`; other destination types return empty results. ## Create Authorization Create an Authorization to request one or more Jumps. API Path: `/jump/authorizations`. Method: `POST`. ### Workflow #### Step 1: Collect Required Information * `destination_type` (string): the value of DestinationType. * `destinations` (string[]): cluster name or cluster IDs. * `privilege` (string): the value of Privilege. * `expiration` (string): the value of Expiration. * `reason` (string): the request reason provided by the user. * `enable_gateway_access` (boolean): Set to true if you need to access the cluster, or if the user indicates they need local cluster access. If `destination_type` is `controlplane` or `serverless` and the user did not specify destinations, you should first list available destinations, then ask the user to choose from them. For other `destination_type` values, ask the user to provide cluster IDs. If the user provides only cluster IDs and does not provide `destination_type`, you should first fetch cluster information from DevOps, then map the cluster type to DestinationType. The mapping is as follows: * DEPLOY_TYPE_DEDICATED -> dedicated, `destinations` should be cluster IDs. * DEPLOY_TYPE_NEXTGEN -> premium, `destinations` should be cluster IDs. * DEPLOY_TYPE_SERVERLESS -> serverless, let the user choose `destinations` from available serverless destinations. * DEPLOY_TYPE_RESOURCE_POOL -> premium_resource_pool, `destinations` should be cluster IDs. ### Step 2: Create an Authorization Call the API to create an Authorization. The request body should come from the information collected in Step 1. For example: ```json { "destination_type": "controlplane", "destinations": [ "base-aws-us-west-2" ], "expiration": "12h", "privilege": "read_write", "enable_gateway_access": true, "reason": "oncall" } ``` ### Step 3: Show the Result After a successful API call, the Authorization enters the "approving" phase and returns an Authorization ID. For example: ```json { "errcode": "OK", "errmsg": "", "trace_id": "20260311134855e3934151b0ba0abe03", "authorization_id": 41729 } ``` You should tell the user the Authorization page URL: `https://ops.tidbcloud.com/jumps/{authorization_id}`. ## List Authorizations List Authorizations using optional filters. API Path: `/jump/authorizations` Method: `GET` ### Query parameters - `page` (integer, optional): page number. Default: `1`. Must be greater than `0`. - `per_page` (integer, optional): number of items per page. Default: `100`. Must be greater than `0` and less than or equal to `100`. - `phase` (string, optional): filter by Authorization Phase. - `destination_type_is` (string, optional): filter by DestinationType. - `destination_id_like` (string, optional): filter by cluster ID. - `show_unaccessible` (bool, optional): If true, return inactive Authorizations. ## Get Authorization Get detailed information about an Authorization. API Path: `/jump/authorizations/{authorization_id}` Method: `GET` ## Cancel Authorization Cancel an Authorization. API Path: `/jump/authorizations/{authorization_id}/cancel` Method: `post` ### Request Body For exmaple: ```json { "force": false } ``` If cancellation fails repeatedly, prompt user for force cancellation and set `force=true` if confirmed. ## Activate User If creating an Authorization returns an error like "user not found", you should first activate the current user's account. API Path: `/jump/jumpserver/users/activate` Method: `post` After the API call succeeds, the user will receive an activation email. Ask the user to check their inbox. Continue the workflow after activation is complete. ## Get Connection URL After the Authorization phase becomes `created`, you can get the login links or kubeconfig for the corresponding Jumps. API Path: `/jump/authorizations/{authorization_id}/connection?method=` Method: `GET` Supported connection method: - `web_terminal`: access via web console, used by human. - `ssh`: access via ssh, used by human. - `gateway`: Available when the Authorization was created with `enable_gateway_access` set to true. Access via kubeconfig, used by humans, agents, or programs. ### Web Terminal If the method is `web_terminal`, the API returns a URL. Tell the user to open the URL to access the cluster. Example response: ```json { "errcode": "OK", "errmsg": "", "trace_id": "20260311140230b61cfaa640763a5675", "connection": { "web_terminal": { "url": "", } } } ``` ### SSH If the method is `ssh`, tell the user to open the Authorization page at `https://ops.tidbcloud.com/jumps/{authorization_id}`, click the Connect button, and follow the guide to access the cluster. Example response: ```json { "errcode": "OK", "errmsg": "", "trace_id": "20260311140230b61cfaa640763a5675", "connection": { "ssh": { "address": "", "base_asset_name": "", "jumppod_namespace": "", "jumppod_name": "" } } } ``` ### Gateway This is available only when the Authorization was created with `enable_gateway_access` set to true. Otherwise, the API returns an error directly. If the method is `gateway`, the response contains a kubeconfig. Save it to a local file. You can then use that file to access the cluster, or tell the user to use that file to access the cluster. Example response: ```json { "errcode": "OK", "errmsg": "", "trace_id": "20260311140230b61cfaa640763a5675", "connection": { "gateway": { "kubeconfig": "" } } } ```