ssh user@hostname
" }, "target_node_user_data_id": { "type": "string", "pattern": "^[0-9]+$", "description": "Target node user data ID", "example": "1" }, "description": { "type": "string", "maxLength": 500, "description": "Description of the software stack (max 500 characters)", "example": "Ubuntu 20.04 LTS with development tools" }, "thumbnail": { "type": "string", "format": "binary", "description": "Thumbnail image for the software stack" } } } } } }, "responses": { "200": { "description": "Software stack created successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "ami-12345678 registered successfully in SOCA as Ubuntu 20.04 LTS" } } } } } }, "400": { "description": "Invalid input parameters" }, "401": { "description": "Missing authentication header" }, "409": { "description": "Software stack name already exists" }, "500": { "description": "AWS API error or internal server error" } } }, "delete": { "operationId": "deleteSoftwareStack", "tags": [ "Target Nodes" ], "summary": "Delete software stacks", "description": "Delete a Target Node Software Stack", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-SOCA-USER", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9._-]+$", "example": "admin" }, "description": "SOCA username for authentication" }, { "in": "header", "name": "X-SOCA-TOKEN", "required": true, "schema": { "type": "string", "minLength": 1, "example": "abc123token" }, "description": "SOCA authentication token" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "software_stack_id" ], "properties": { "software_stack_id": { "type": "string", "pattern": "^[0-9]+$", "description": "ID of software stack to delete", "example": "1" } } } } } }, "responses": { "200": { "description": "Successfully deleted software stack", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Software Stack removed from SOCA" } } } } } }, "400": { "description": "Invalid software_stack_id parameter" }, "401": { "description": "Missing authentication header" }, "404": { "description": "Software stack not found" } } }, "put": { "operationId": "updateSoftwareStack", "tags": [ "Target Nodes" ], "summary": "Modify an existing software stack", "description": "Modify an existing software stack with AMI and configuration details", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-SOCA-USER", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9._-]+$", "example": "admin" }, "description": "SOCA username for authentication" }, { "in": "header", "name": "X-SOCA-TOKEN", "required": true, "schema": { "type": "string", "minLength": 1, "example": "abc123token" }, "description": "SOCA authentication token" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "software_stack_id", "ami_id", "root_size", "target_node_profile_id", "target_node_user_data_id", "connection_string" ], "properties": { "software_stack_id": { "type": "string", "pattern": "^[0-9]+$", "description": "ID of software stack to update", "example": "1" }, "ami_id": { "type": "string", "pattern": "^ami-[0-9a-f]{8,17}$", "description": "AWS AMI ID", "example": "ami-12345678" }, "root_size": { "type": "string", "pattern": "^[0-9]+$", "description": "Root volume size in GB", "example": "20" }, "launch_tenancy": { "type": "string", "enum": [ "default", "dedicated", "host" ], "description": "EC2 tenancy type", "example": "default" }, "launch_host": { "type": "string", "pattern": "^h-[0-9a-f]{8,17}$", "description": "Dedicated host ID (required if tenancy is 'host')", "example": "h-12345678" }, "user_data_variables": { "type": "string", "pattern": "^[a-zA-Z0-9_]+=.*$", "description": "User data variables in key=value,key2=value2 format", "example": "env=prod,region=us-east-1" }, "target_node_profile_id": { "type": "string", "pattern": "^[0-9]+$", "description": "Target node profile ID", "example": "1" }, "connection_string": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Connection instructions (HTML allowed)", "example": "ssh user@hostname
" }, "target_node_user_data_id": { "type": "string", "pattern": "^[0-9]+$", "description": "Target node user data ID", "example": "1" }, "description": { "type": "string", "maxLength": 500, "description": "Description of the software stack (max 500 characters)", "example": "Ubuntu 20.04 LTS with development tools" }, "thumbnail": { "type": "string", "format": "binary", "description": "Thumbnail image for the software stack" } } } } } }, "responses": { "200": { "description": "Software stack updated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "ami-12345678 updated successfully in SOCA" } } } } } }, "400": { "description": "Invalid input parameters" }, "401": { "description": "Missing authentication header" }, "404": { "description": "Software stack not found" }, "500": { "description": "AWS API error or internal server error" } } } }, "/api/target_nodes/delete": { "delete": { "operationId": "deleteTargetNodeSession", "tags": [ "Target Nodes" ], "summary": "Delete an existing target node session", "description": "Terminates and removes a target node session including associated AWS resources", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-SOCA-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "john.doe" }, { "name": "X-SOCA-TOKEN", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "Authentication token for the SOCA user", "example": "abc123token" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "session_uuid" ], "properties": { "session_uuid": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID of the target node session to delete", "example": "550e8400-e29b-41d4-a716-446655440000" } } } } } }, "responses": { "200": { "description": "Target node session deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Your Target Node is about to be terminated" } } } } } }, "400": { "description": "Bad request - missing or invalid parameters" }, "401": { "description": "Authentication required" }, "404": { "description": "Session not found or not active" }, "500": { "description": "Internal server error" } } } }, "/api/target_nodes/stop": { "put": { "operationId": "stopTargetNode", "tags": [ "Target Nodes" ], "summary": "Stop a running target node session", "description": "Stop or hibernate a running target node session by session UUID", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-SOCA-USER", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9._-]+$", "example": "john.doe" }, "description": "SOCA username for authentication" }, { "in": "header", "name": "X-SOCA-TOKEN", "required": true, "schema": { "type": "string", "minLength": 1, "example": "abc123def456" }, "description": "SOCA authentication token" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "session_uuid" ], "properties": { "session_uuid": { "type": "string", "format": "uuid", "description": "UUID of the target node session to stop", "example": "12345678-1234-1234-1234-123456789abc" } } } } } }, "responses": { "200": { "description": "Target node stop initiated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Your target node will be stopped soon." } } } } } }, "400": { "description": "Missing required parameter or session already stopped", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "enum": [ "Missing required parameter: session_uuid", "Your target node is already stopped." ], "example": "Missing required parameter: session_uuid" } } } } } }, "401": { "description": "Missing authentication header", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Missing X-SOCA-USER header" } } } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to find this session. Please refresh your browser and try again." } } } } } }, "500": { "description": "AWS API error or database error", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "enum": [ "Unable to stop/hibernate instance due to AWS error", "Unable to set session_state to stopped due to database error" ], "example": "Unable to stop/hibernate instance due to AWS error" } } } } } } } } }, "/api/target_nodes/create": { "post": { "operationId": "createTargetNodeSession", "tags": [ "Target Nodes" ], "summary": "Create a new target node session for CAE simulations", "description": "Creates a new target node session with specified configuration including instance type, software stack, and networking parameters", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-SOCA-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "john.doe" }, { "name": "X-SOCA-TOKEN", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "Authentication token for the SOCA user", "example": "abc123token" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "instance_type", "session_name", "software_stack_id", "project" ], "properties": { "instance_type": { "type": "string", "pattern": "^[a-z0-9]+\\.[a-z0-9]+$", "description": "AWS EC2 instance type for the target node", "example": "m5.large" }, "session_name": { "type": "string", "pattern": "^[a-zA-Z0-9-]{1,32}$", "maxLength": 32, "description": "Name for the target node session (max 32 chars, alphanumeric and hyphens only)", "example": "my-simulation-session" }, "software_stack_id": { "type": "string", "pattern": "^[0-9]+$", "description": "ID of the software stack to use", "example": "123" }, "project": { "type": "string", "minLength": 1, "description": "Project name for the target node session", "example": "default" }, "disk_size": { "type": "string", "pattern": "^[0-9]+$", "description": "Root disk size in GB", "example": "100" }, "subnet_id": { "type": "string", "pattern": "^subnet-[a-f0-9]{8,17}$", "description": "AWS subnet ID (random private subnet used if not specified)", "example": "subnet-12345678" }, "tenancy": { "type": "string", "enum": [ "default", "dedicated", "host" ], "description": "EC2 tenancy type", "example": "default" } } } } } }, "responses": { "200": { "description": "Target node session created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Session my-simulation-session started successfully." } } } } } }, "400": { "description": "Bad request - missing or invalid parameters" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden - user quota exceeded or access denied" }, "500": { "description": "Internal server error" } } } }, "/api/target_nodes/user_data": { "get": { "operationId": "getUserDataTemplates", "tags": [ "Target Nodes", "User Data" ], "summary": "Get user data templates", "description": "Retrieve user data templates for target nodes", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-SOCA-USER", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9._-]+$", "example": "admin" }, "description": "SOCA username for authentication" }, { "in": "header", "name": "X-SOCA-TOKEN", "required": true, "schema": { "type": "string", "minLength": 1, "example": "abc123token" }, "description": "SOCA authentication token" }, { "in": "query", "name": "template_id", "required": false, "schema": { "type": "string", "pattern": "^[0-9]+$", "example": "1" }, "description": "Specific template ID to retrieve" } ], "responses": { "200": { "description": "User data templates retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "object", "example": { "1": { "id": 1, "template_name": "default", "description": "Default template" } } } } } } } }, "400": { "description": "Invalid template_id parameter" }, "401": { "description": "Authentication required" }, "403": { "description": "Admin access required" } } }, "post": { "operationId": "createUserDataTemplate", "tags": [ "Target Nodes", "User Data" ], "summary": "Create a new user data template", "description": "Create a new user data template for target nodes", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-SOCA-USER", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9._-]+$", "example": "admin" }, "description": "SOCA username for authentication" }, { "in": "header", "name": "X-SOCA-TOKEN", "required": true, "schema": { "type": "string", "minLength": 1, "example": "abc123token" }, "description": "SOCA authentication token" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "template_name", "description", "user_data" ], "properties": { "template_name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9._-]+$", "description": "Name for the user data template", "example": "my-custom-template" }, "description": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Description of the template (max 500 characters)", "example": "Custom user data template for CAE workloads" }, "user_data": { "type": "string", "minLength": 1, "maxLength": 16384, "pattern": "^#!/bin/bash", "description": "EC2 user data script (max 16KB)", "example": "#!/bin/bash echo 'Hello World'" } } } } } }, "responses": { "200": { "description": "User data template created successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "User Data template has been created successfully" } } } } } }, "400": { "description": "Missing required parameters or validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Admin access required" }, "409": { "description": "Template name already exists" } } }, "delete": { "operationId": "deleteUserDataTemplate", "tags": [ "Target Nodes", "User Data" ], "summary": "Delete a user data template", "description": "Delete a user data template for target nodes", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-SOCA-USER", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9._-]+$", "example": "admin" }, "description": "SOCA username for authentication" }, { "in": "header", "name": "X-SOCA-TOKEN", "required": true, "schema": { "type": "string", "minLength": 1, "example": "abc123token" }, "description": "SOCA authentication token" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "template_id" ], "properties": { "template_id": { "type": "string", "pattern": "^[0-9]+$", "description": "ID of the template to delete", "example": "2" } } } } } }, "responses": { "200": { "description": "User data template deleted successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "User Data Template deleted successfully" } } } } } }, "400": { "description": "Missing template_id or invalid ID" }, "401": { "description": "Authentication required" }, "403": { "description": "Admin access required or default template cannot be deleted" }, "404": { "description": "Template not found" }, "409": { "description": "Template is in use by active software stacks" } } }, "put": { "operationId": "updateUserDataTemplate", "tags": [ "Target Nodes", "User Data" ], "summary": "Update an existing user data template", "description": "Update an existing user data template for target nodes", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-SOCA-USER", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9._-]+$", "example": "admin" }, "description": "SOCA username for authentication" }, { "in": "header", "name": "X-SOCA-TOKEN", "required": true, "schema": { "type": "string", "minLength": 1, "example": "abc123token" }, "description": "SOCA authentication token" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "template_id", "description", "user_data" ], "properties": { "template_id": { "type": "string", "pattern": "^[0-9]+$", "description": "ID of the template to update", "example": "2" }, "description": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Updated description (max 500 characters)", "example": "Updated custom template description" }, "user_data": { "type": "string", "minLength": 1, "maxLength": 16384, "pattern": "^#!/bin/bash ", "description": "Updated EC2 user data script (max 16KB)", "example": "#!/bin/bash echo 'Updated script'" } } } } } }, "responses": { "200": { "description": "User data template updated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "User Data Template has been updated successfully" } } } } } }, "400": { "description": "Missing required parameters or validation error" }, "401": { "description": "Authentication required" }, "403": { "description": "Admin access required" }, "404": { "description": "Template not found" } } } }, "/api/target_nodes/start": { "put": { "operationId": "startTargetNode", "tags": [ "Target Nodes" ], "summary": "Start a stopped target node session", "description": "Restart a previously stopped target node session by session UUID", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-SOCA-USER", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9._-]+$", "example": "john.doe" }, "description": "SOCA username for authentication" }, { "in": "header", "name": "X-SOCA-TOKEN", "required": true, "schema": { "type": "string", "minLength": 1, "example": "abc123def456" }, "description": "SOCA authentication token" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "session_uuid" ], "properties": { "session_uuid": { "type": "string", "format": "uuid", "description": "UUID of the target node session to start", "example": "12345678-1234-1234-1234-123456789abc" } } } } } }, "responses": { "200": { "description": "Target node start initiated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Your target node is starting" } } } } } }, "400": { "description": "Missing required parameter or invalid session state", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "enum": [ "Missing required parameter: session_uuid", "This target node is still being started. Please wait a little bit before restarting this session.", "This target node seems to be already running." ], "example": "Missing required parameter: session_uuid" } } } } } }, "401": { "description": "Missing authentication header", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Missing X-SOCA-USER header" } } } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to find this session. Please refresh your browser and try again." } } } } } }, "500": { "description": "AWS API error or internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "enum": [ "Unable to create capacity reservation", "Unable to start instance due to AWS error", "Your current target node is not yet stopped. Please wait a little longer" ], "example": "Unable to start instance due to AWS error" } } } } } } } } }, "/api/target_nodes/profiles": { "get": { "operationId": "getTargetNodeProfiles", "tags": [ "Target Nodes" ], "summary": "Retrieve target node profiles", "description": "Returns target node profile information including allowed instance types and subnet configurations", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-SOCA-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin.user" }, { "name": "X-SOCA-TOKEN", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "Authentication token for the SOCA user", "example": "abc123token" }, { "name": "profile_id", "in": "query", "schema": { "type": "string", "pattern": "^[0-9]+$" }, "required": false, "description": "Specific profile ID to retrieve (returns all if not specified)", "example": "1" } ], "responses": { "200": { "description": "Target node profiles retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "object", "description": "Dictionary of profile IDs mapped to profile details", "additionalProperties": { "type": "object", "properties": { "id": { "type": "integer" }, "profile_name": { "type": "string" }, "allowed_instance_types": { "type": "string" }, "max_root_size": { "type": "integer" } } } } } } } } }, "400": { "description": "Bad request - invalid profile ID" }, "401": { "description": "Authentication required" }, "403": { "description": "Admin access required" }, "500": { "description": "Internal server error" } } }, "post": { "operationId": "createTargetNodeProfile", "tags": [ "Target Nodes" ], "summary": "Create a new target node profile", "description": "Creates a new target node profile with specified instance types, subnets, and resource limits", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-SOCA-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin.user" }, { "name": "X-SOCA-TOKEN", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "Authentication token for the SOCA user", "example": "abc123token" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "profile_name", "pattern_allowed_instance_types", "allowed_subnet_ids", "max_root_size" ], "properties": { "profile_name": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$", "minLength": 1, "maxLength": 100, "description": "Name for the new profile", "example": "high-performance-profile" }, "pattern_allowed_instance_types": { "type": "string", "pattern": "^[a-z0-9.*,\\s]+$", "description": "Comma-separated list of allowed EC2 instance type patterns", "example": "m5.*,c5.*" }, "allowed_subnet_ids": { "type": "string", "pattern": "^subnet-[a-f0-9]{8,17}(,subnet-[a-f0-9]{8,17})*$", "description": "Comma-separated list of allowed subnet IDs", "example": "subnet-12345678,subnet-87654321" }, "max_root_size": { "type": "string", "pattern": "^[0-9]+$", "description": "Maximum root disk size in GB", "example": "100" }, "description": { "type": "string", "maxLength": 500, "description": "Profile description (max 500 characters)", "example": "Profile for high-performance computing workloads" } } } } } }, "responses": { "200": { "description": "Target node profile created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "high-performance-profile registered successfully in SOCA" } } } } } }, "400": { "description": "Bad request - missing or invalid parameters" }, "401": { "description": "Authentication required" }, "403": { "description": "Admin access required" }, "409": { "description": "Conflict - profile name already exists" }, "500": { "description": "Internal server error" } } }, "delete": { "operationId": "deleteTargetNodeProfile", "tags": [ "Target Nodes" ], "summary": "Delete an existing target node profile", "description": "Deactivates a target node profile if it's not being used by any software stacks", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-SOCA-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin.user" }, { "name": "X-SOCA-TOKEN", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "Authentication token for the SOCA user", "example": "abc123token" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "profile_id" ], "properties": { "profile_id": { "type": "string", "pattern": "^[0-9]+$", "description": "ID of the profile to delete", "example": "2" } } } } } }, "responses": { "200": { "description": "Target node profile deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Target Node Profile removed from SOCA" } } } } } }, "400": { "description": "Bad request - missing or invalid parameters" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden - cannot delete default profile or profile in use" }, "404": { "description": "Profile not found or already deactivated" }, "500": { "description": "Internal server error" } } }, "put": { "operationId": "updateTargetNodeProfile", "tags": [ "Target Nodes" ], "summary": "Update an existing target node profile", "description": "Updates the configuration of an existing target node profile including instance types, subnets, and resource limits", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-SOCA-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin.user" }, { "name": "X-SOCA-TOKEN", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "Authentication token for the SOCA user", "example": "abc123token" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "profile_id", "pattern_allowed_instance_types", "allowed_subnet_ids", "max_root_size" ], "properties": { "profile_id": { "type": "string", "pattern": "^[0-9]+$", "description": "ID of the profile to update", "example": "2" }, "pattern_allowed_instance_types": { "type": "string", "pattern": "^[a-z0-9.*,\\s]+$", "description": "Comma-separated list of allowed EC2 instance type patterns", "example": "m5.*,c5.*,r5.*" }, "allowed_subnet_ids": { "type": "string", "pattern": "^subnet-[a-f0-9]{8,17}(,subnet-[a-f0-9]{8,17})*$", "description": "Comma-separated list of allowed subnet IDs", "example": "subnet-12345678,subnet-87654321" }, "max_root_size": { "type": "string", "pattern": "^[0-9]+$", "description": "Maximum root disk size in GB", "example": "200" }, "description": { "type": "string", "maxLength": 500, "description": "Profile description (max 500 characters)", "example": "Updated profile for high-performance computing workloads" } } } } } }, "responses": { "200": { "description": "Target node profile updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Profile updated successfully" } } } } } }, "400": { "description": "Bad request - missing or invalid parameters" }, "401": { "description": "Authentication required" }, "403": { "description": "Admin access required" }, "404": { "description": "Profile not found" }, "500": { "description": "Internal server error" } } } }, "/api/target_nodes/resize": { "put": { "operationId": "resizeTargetNode", "tags": [ "Target Nodes" ], "summary": "Resize target node instance type", "description": "Modify the instance type of a target node session. The session must be in stopped state.", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-SOCA-USER", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9._-]+$", "example": "john.doe" }, "description": "SOCA username for authentication" }, { "in": "header", "name": "X-SOCA-TOKEN", "required": true, "schema": { "type": "string", "minLength": 1, "example": "abc123def456" }, "description": "SOCA authentication token" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "session_uuid", "instance_type" ], "properties": { "session_uuid": { "type": "string", "format": "uuid", "description": "UUID of the virtual desktop session to resize", "example": "12345678-1234-1234-1234-123456789abc" }, "instance_type": { "type": "string", "pattern": "^[a-z0-9]+\\.[a-z0-9]+$", "description": "New EC2 instance type for the virtual desktop", "example": "m5.large", "enum": [ "t3.micro", "t3.small", "t3.medium", "t3.large", "m5.large", "m5.xlarge", "c5.large", "c5.xlarge" ] } } } } } }, "responses": { "200": { "description": "Virtual desktop successfully resized", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Your virtual desktop has been updated" } } } } } }, "400": { "description": "Bad request - missing parameters or invalid instance type", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error_code", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "string", "example": "CLIENT_MISSING_PARAMETER" }, "message": { "type": "string", "example": "Missing required parameter: session_uuid" } } } } } }, "401": { "description": "Unauthorized - invalid or missing authentication headers", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error_code", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "string", "example": "CLIENT_MISSING_HEADER" }, "message": { "type": "string", "example": "Missing required header: X-SOCA-USER" } } } } } }, "403": { "description": "Forbidden - session not owned by user or session not in stopped state", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error_code", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "string", "example": "VIRTUAL_DESKTOP_MODIFY_ERROR" }, "message": { "type": "string", "example": "This Virtual Desktop is not stopped. You can only modify a stopped desktop." } } } } } }, "500": { "description": "Internal server error - AWS API or database error", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error_code", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "string", "example": "VIRTUAL_DESKTOP_MODIFY_ERROR" }, "message": { "type": "string", "example": "Unable to modify this desktop because of AWS error" } } } } } } } } }, "/api/system/files": { "get": { "operationId": "getFileContent", "tags": [ "System Files" ], "summary": "GET /api/system/files", "description": "GET operation for /api/system/files", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-SOCA-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin" }, { "name": "X-SOCA-TOKEN", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA authentication token", "example": "abc123token" }, { "name": "file", "in": "query", "schema": { "type": "string", "pattern": "^/[a-zA-Z0-9_./\\-]+$", "minLength": 1 }, "required": true, "description": "Full path to the file to read", "example": "/home/user/config.txt" } ], "responses": { "200": { "description": "File content retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "File content here..." } } } } } }, "400": { "description": "Missing file parameter or file not found" }, "401": { "description": "Authentication required" }, "403": { "description": "Permission denied or restricted path" } } }, "post": { "operationId": "createOrUpdateFile", "tags": [ "System Files" ], "summary": "POST /api/system/files", "description": "POST operation for /api/system/files", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-SOCA-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin" }, { "name": "X-SOCA-TOKEN", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA authentication token", "example": "abc123token" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "file_name", "file_content" ], "properties": { "file_name": { "type": "string", "format": "base64", "minLength": 1, "description": "Base64 encoded file path", "example": "L2hvbWUvdXNlci9jb25maWcudHh0" }, "file_content": { "type": "string", "format": "base64", "minLength": 1, "description": "Base64 encoded file content", "example": "SGVsbG8gV29ybGQ=" } } } } } }, "responses": { "200": { "description": "File created/updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "File Updated." } } } } } }, "400": { "description": "Missing parameters or invalid base64 encoding" }, "401": { "description": "Authentication required" }, "403": { "description": "Permission denied to write file" } } } }, "/api/applications/export": { "get": { "operationId": "exportApplicationProfile", "tags": [ "Applications" ], "summary": "Export application profile", "description": "Exports an application profile configuration for backup or migration (admin access required)", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-SOCA-USER", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9._-]+$" }, "description": "SOCA username for authentication (must be admin)", "example": "admin.user" }, { "in": "header", "name": "X-SOCA-TOKEN", "required": true, "schema": { "type": "string", "minLength": 10, "maxLength": 1000 }, "description": "SOCA authentication token", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" }, { "in": "query", "name": "application_id", "required": true, "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "ID of the application profile to export", "example": "1" } ], "responses": { "200": { "description": "Application profile exported successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "object", "properties": { "Instructions": { "type": "string", "example": "https://awslabs.github.io/scale-out-computing-on-aws-documentation/documentation/web-interface/import-export-application-profiles" }, "profile_form": { "type": "string", "example": "" }, "profile_job": { "type": "string", "example": "#!/bin/bash module load ansys fluent -g" }, "profile_interpreter": { "type": "string", "example": "bash" }, "profile_thumbnail": { "type": "string", "example": "data:image/png;base64,..." } } } } } } } }, "400": { "description": "Missing application_id parameter", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Missing required parameter: application_id" } } } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "integer", "example": 403 }, "message": { "type": "string", "example": "Admin access required" } } } } } }, "404": { "description": "Application profile not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Application does not exist" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Database error occurred" } } } } } } } } }, "/api/applications/application": { "post": { "operationId": "createApplicationProfile", "tags": [ "Applications" ], "summary": "Create application profile", "description": "Creates a new application profile with job submission form and script (admin access required)", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-SOCA-USER", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9._-]+$" }, "description": "SOCA username for authentication (must be admin)", "example": "admin.user" }, { "in": "header", "name": "X-SOCA-TOKEN", "required": true, "schema": { "type": "string", "minLength": 10, "maxLength": 1000 }, "description": "SOCA authentication token", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "profile_name", "submit_job_form", "submit_job_script", "submit_job_interpreter" ], "properties": { "profile_name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Name for the application profile", "example": "ANSYS Fluent" }, "submit_job_form": { "type": "string", "minLength": 1, "description": "HTML form for job submission parameters", "example": "" }, "submit_job_script": { "type": "string", "minLength": 1, "description": "Job submission script template", "example": "#!/bin/bash module load ansys fluent -g" }, "submit_job_interpreter": { "type": "string", "description": "Script interpreter (scheduler name or system shell)", "example": "bash" }, "thumbnail_b64": { "type": "string", "format": "base64", "description": "Base64 encoded thumbnail image for the application", "example": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==" } } } } } }, "responses": { "200": { "description": "Application profile created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "ANSYS Fluent created successfully" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Missing required parameter: profile_name" } } } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "integer", "example": 403 }, "message": { "type": "string", "example": "Admin access required" } } } } } }, "500": { "description": "Server error during creation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to add new application db entry" } } } } } } } }, "put": { "operationId": "updateApplicationProfile", "tags": [ "Applications" ], "summary": "Update application profile", "description": "Updates an existing application profile with new configuration (admin access required)", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-SOCA-USER", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9._-]+$" }, "description": "SOCA username for authentication (must be admin)", "example": "admin.user" }, { "in": "header", "name": "X-SOCA-TOKEN", "required": true, "schema": { "type": "string", "minLength": 10, "maxLength": 1000 }, "description": "SOCA authentication token", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "application_id" ], "properties": { "application_id": { "type": "string", "pattern": "^[0-9]+$", "description": "ID of the application profile to update", "example": "1" }, "profile_name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Updated name for the application profile", "example": "ANSYS Fluent 2024" }, "submit_job_form": { "type": "string", "description": "Updated HTML form for job submission", "example": "" }, "submit_job_script": { "type": "string", "description": "Updated job submission script template", "example": "#!/bin/bash module load ansys/2024 fluent -g" }, "submit_job_interpreter": { "type": "string", "description": "Updated script interpreter", "example": "bash" }, "thumbnail_b64": { "type": "string", "format": "base64", "description": "Updated base64 encoded thumbnail image", "example": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==" } } } } } }, "responses": { "200": { "description": "Application profile updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Application updated successfully" } } } } } }, "400": { "description": "Missing or invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Missing required parameter: application_id" } } } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "integer", "example": 403 }, "message": { "type": "string", "example": "Admin access required" } } } } } }, "404": { "description": "Application profile not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Application not found" } } } } } }, "500": { "description": "Server error during update", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to edit existing application db entry" } } } } } } } }, "delete": { "operationId": "deleteApplicationProfile", "tags": [ "Applications" ], "summary": "Delete application profile", "description": "Deletes an existing application profile from the database (admin access required)", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-SOCA-USER", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9._-]+$" }, "description": "SOCA username for authentication (must be admin)", "example": "admin.user" }, { "in": "header", "name": "X-SOCA-TOKEN", "required": true, "schema": { "type": "string", "minLength": 10, "maxLength": 1000 }, "description": "SOCA authentication token", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "application_id" ], "properties": { "application_id": { "type": "string", "pattern": "^[0-9]+$", "description": "ID of the application profile to delete", "example": "1" } } } } } }, "responses": { "200": { "description": "Application profile deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Application deleted successfully" } } } } } }, "400": { "description": "Missing application_id parameter", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Missing required parameter: application_id" } } } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "integer", "example": 403 }, "message": { "type": "string", "example": "Admin access required" } } } } } }, "500": { "description": "Server error during deletion", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to delete application db entry" } } } } } } } } }, "/api/applications/list_applications": { "get": { "operationId": "listApplications", "tags": [ "Applications" ], "summary": "Get application profiles", "description": "Retrieves all application profiles (admin access required)", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-SOCA-USER", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9._-]+$" }, "description": "SOCA username for authentication (must be admin)", "example": "admin.user" }, { "in": "header", "name": "X-SOCA-TOKEN", "required": true, "schema": { "type": "string", "minLength": 10, "maxLength": 1000 }, "description": "SOCA authentication token", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" }, { "in": "query", "name": "application_id", "required": false, "schema": { "type": "string", "pattern": "^[0-9]+$", "example": "1" }, "description": "Specific application ID to retrieve (returns all if not specified)" } ], "responses": { "200": { "description": "Application profiles retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "object", "additionalProperties": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "profile_name": { "type": "string", "example": "ANSYS Fluent" }, "created_by": { "type": "string", "example": "admin" }, "profile_form": { "type": "string", "example": "" }, "profile_job": { "type": "string", "example": "#!/bin/bash ..." }, "profile_interpreter": { "type": "string", "example": "bash" }, "profile_thumbnail": { "type": "string", "example": "data:image/png;base64,..." }, "acl_allowed_users": { "type": "string", "example": "user1,user2" }, "acl_restricted_users": { "type": "string", "example": "restricted_user" }, "created_on": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" }, "deactivated_on": { "type": "string", "format": "date-time", "nullable": true, "example": null } } } } } } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "integer", "example": 403 }, "message": { "type": "string", "example": "Admin access required" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Error retrieving applications profile list, check logs for more details." } } } } } } } } }, "/api/applications/import": { "post": { "operationId": "importApplicationProfile", "tags": [ "Applications" ], "summary": "Import application profile", "description": "Imports an application profile from a JSON file (admin access required)", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-SOCA-USER", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9._-]+$" }, "description": "SOCA username for authentication (must be admin)", "example": "admin.user" }, { "in": "header", "name": "X-SOCA-TOKEN", "required": true, "schema": { "type": "string", "minLength": 10, "maxLength": 1000 }, "description": "SOCA authentication token", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "app_profile" ], "properties": { "app_profile": { "type": "string", "format": "binary", "description": "JSON file containing application profile configuration" } } } } } }, "responses": { "200": { "description": "Application profile imported successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Application Imported successfully" } } } } } }, "400": { "description": "Invalid JSON file or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "This does not seem to be a valid JSON" } } } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "integer", "example": 403 }, "message": { "type": "string", "example": "Admin access required" } } } } } }, "500": { "description": "Server error during import", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to import file. See log for details" } } } } } } } } }, "/api/cost_management/budget": { "get": { "operationId": "getAwsBudgetInfo", "tags": [ "Cost Management" ], "summary": "Retrieve AWS budget information for a project", "description": "Gets current spend, forecasted spend, total budget, and usage percentage for a specific project's AWS budget", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-SOCA-USER", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9._-]+$" }, "description": "SOCA username for authentication", "example": "john.doe" }, { "name": "X-SOCA-TOKEN", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "SOCA authentication token", "example": "abc123token456" }, { "name": "project_name", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9._-]+$" }, "description": "Name of the project", "example": "my-research-project" } ], "responses": { "200": { "description": "Budget information retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "object", "required": [ "budget_exist", "current_spend", "forecast_spend", "total_budget", "usage_pct" ], "properties": { "budget_exist": { "type": "boolean", "description": "Whether a budget exists for this project", "example": true }, "current_spend": { "type": "number", "minimum": 0, "description": "Current spend amount in USD", "example": 1250.75 }, "forecast_spend": { "type": "number", "minimum": 0, "description": "Forecasted spend amount in USD", "example": 1800.5 }, "total_budget": { "type": "number", "minimum": 0, "description": "Total budget amount in USD", "example": 5000.0 }, "usage_pct": { "type": "number", "minimum": 0, "maximum": 100, "description": "Usage percentage of total budget", "example": 25.02 }, "forecast_pct": { "type": "number", "minimum": 0, "description": "Forecasted usage percentage of total budget", "example": 36.01 } } } } } } } }, "400": { "description": "Bad request - missing required parameters", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Missing required parameter: project_name" } } } } } }, "404": { "description": "Project or budget not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Project my-research-project not found or deactivated" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to retrieve budget information, check log for more details" } } } } } } } } }, "/api/cost_management/pricing": { "get": { "operationId": "calculateAwsPricing", "tags": [ "Cost Management" ], "summary": "Calculate AWS pricing for compute and storage resources", "description": "Estimates the cost of running a job with specified compute and storage requirements", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-SOCA-USER", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9._-]+$" }, "description": "SOCA username for authentication", "example": "john.doe" }, { "name": "X-SOCA-TOKEN", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "SOCA authentication token", "example": "abc123token456" }, { "name": "instance_type", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]+\\.[a-z0-9]+$" }, "description": "EC2 instance type", "example": "m5.large" }, { "name": "wall_time", "in": "query", "required": false, "schema": { "type": "string", "pattern": "f'^([0-9]{1,2}):([0-5][0-9]):([0-5][0-9])$'", "default": "01:00:00" }, "description": "Job duration in HH:MM:SS format", "example": "02:30:00" }, { "name": "vcpus", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "description": "Number of vCPUs to allocate", "example": 4 }, { "name": "scratch_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 }, "description": "Scratch storage size in GB", "example": 100 }, { "name": "root_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 8, "maximum": 1000, "default": 40 }, "description": "Root disk size in GB", "example": 50 }, { "name": "fsx_capacity", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 }, "description": "FSx storage capacity in GB", "example": 1200 }, { "name": "fsx_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "SCRATCH_1", "SCRATCH_2", "PERSISTENT_1", "PERSISTENT_2" ], "default": "SCRATCH_2" }, "description": "FSx storage type", "example": "SCRATCH_2" } ], "responses": { "200": { "description": "Pricing calculation successful", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "object", "required": [ "compute", "estimated_total_cost", "estimated_hourly_cost", "estimated_storage_cost" ], "properties": { "compute": { "type": "object", "required": [ "on_demand_hourly_rate", "reserved_hourly_rate", "estimated_on_demand_cost", "estimated_reserved_cost", "nodes", "walltime", "instance_type" ], "properties": { "on_demand_hourly_rate": { "type": "number", "minimum": 0, "example": 0.096 }, "reserved_hourly_rate": { "type": "number", "minimum": 0, "example": 0.058 }, "estimated_on_demand_cost": { "type": "number", "minimum": 0, "example": 0.192 }, "estimated_reserved_cost": { "type": "number", "minimum": 0, "example": 0.116 }, "nodes": { "type": "integer", "minimum": 1, "example": 1 }, "walltime": { "type": "number", "minimum": 0, "example": 2.5 }, "instance_type": { "type": "string", "example": "m5.large" }, "vcpus": { "type": "integer", "nullable": true, "example": 4 } } }, "estimated_total_cost": { "type": "number", "minimum": 0, "example": 0.205 }, "estimated_hourly_cost": { "type": "number", "minimum": 0, "example": 0.103 }, "estimated_storage_cost": { "type": "number", "minimum": 0, "example": 0.013 }, "scratch_size": { "type": "string", "example": "0.007" }, "root_size": { "type": "string", "example": "0.003" }, "fsx_capacity": { "type": "string", "example": "0.003" }, "storage_pct": { "type": "number", "minimum": 0, "maximum": 100, "example": 6.34 }, "compute_pct": { "type": "string", "example": "93.66" } } } } } } } }, "400": { "description": "Invalid parameters or wall_time format", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "wall_time must use HH:MM:SS format and only use valid numbers" } } } } } }, "401": { "description": "Unauthorized - invalid authentication", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Authentication failed" } } } } } }, "404": { "description": "Instance type pricing not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to retrieve price for m5.large" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to get compute price. Instance type may be incorrect or region name not tracked correctly?" } } } } } } } } }, "/api/cost_management/budgets": { "get": { "operationId": "listAwsBudgets", "tags": [ "Cost Management" ], "summary": "List all available AWS budgets", "description": "Retrieves a list of all AWS budgets available in the current account", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-SOCA-USER", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9._-]+$" }, "description": "SOCA username for authentication", "example": "john.doe" }, { "name": "X-SOCA-TOKEN", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "SOCA authentication token", "example": "abc123token456" } ], "responses": { "200": { "description": "List of available budgets retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "List of budget names", "example": [ "monthly-budget", "quarterly-budget", "project-alpha-budget" ] } } } } } }, "401": { "description": "Unauthorized - invalid authentication", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Authentication failed" } } } } } }, "403": { "description": "Forbidden - insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Admin access required" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Error retrieving budget list, check logs for more details." } } } } } } } } }, "/api/containers/ecr/repository": { "get": { "operationId": "listEcrRepositoryImages", "tags": [ "Elastic Container Registry (ECR)" ], "summary": "Retrieve ECR repository images", "description": "Lists Amazon ECR images from repositories tagged with the current SOCA cluster ID", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-SOCA-USER", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9._-]+$" }, "description": "SOCA username for authentication", "example": "john.doe" }, { "name": "X-SOCA-TOKEN", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "SOCA authentication token", "example": "abc123token456" }, { "name": "repository", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9._-]+(,[a-zA-Z0-9._-]+)*$", "maxLength": 1000 }, "description": "Comma-separated list of ECR repository names to inspect", "example": "my-app,my-service" } ], "responses": { "200": { "description": "ECR images retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "required": [ "imageDigest", "imageUri", "pushedAt", "imageSizeInMB" ], "properties": { "imageTag": { "type": "string", "nullable": true, "example": "latest" }, "imageDigest": { "type": "string", "pattern": "f'^sha256:[a-f0-9]{64}$'", "example": "sha256:abc123def456" }, "imageUri": { "type": "string", "format": "uri", "example": "123456789.dkr.ecr.us-east-1.amazonaws.com/my-app:latest" }, "pushedAt": { "type": "string", "format": "date-time", "example": "2024-01-15 10:30:00" }, "imageSizeInMB": { "type": "number", "minimum": 0, "example": 125.5 } } } }, "example": { "my-app": [ { "imageTag": "latest", "imageDigest": "sha256:abc123def456", "imageUri": "123456789.dkr.ecr.us-east-1.amazonaws.com/my-app:latest", "pushedAt": "2024-01-15 10:30:00", "imageSizeInMB": 125.5 } ] } } } } } } }, "400": { "description": "Bad request - invalid parameters", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid repository name format" } } } } } }, "401": { "description": "Unauthorized - invalid authentication", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Authentication failed" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to list ECR images" } } } } } } } } }, "/api/containers/eks/list_clusters": { "get": { "operationId": "listEksClusters", "tags": [ "Elastic Kubernetes Service (EKS)" ], "summary": "List available EKS clusters", "description": "Retrieves a list of EKS clusters that are tagged for visibility with the current SOCA cluster ID", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-SOCA-USER", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9._-]+$" }, "description": "SOCA username for authentication", "example": "john.doe" }, { "name": "X-SOCA-TOKEN", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "SOCA authentication token", "example": "abc123token456" }, { "name": "cluster", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9._-]+(,[a-zA-Z0-9._-]+)*$", "maxLength": 1000 }, "description": "Comma-separated list of specific cluster names to validate (optional)", "example": "cluster1,cluster2" } ], "responses": { "200": { "description": "EKS clusters retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9._-]+$" }, "description": "List of available EKS cluster names", "example": [ "my-soca-cluster-1", "my-soca-cluster-2" ] } } } } } }, "401": { "description": "Unauthorized - invalid authentication", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Authentication failed" } } } } } }, "403": { "description": "Forbidden - insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Access denied to EKS resources" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to list EKS clusters" } } } } } } } } }, "/api/containers/eks/job": { "get": { "operationId": "getEksJobDetails", "tags": [ "Elastic Kubernetes Service (EKS)" ], "summary": "Retrieve details of a specific EKS job", "description": "Gets detailed information about an EKS job including status, configuration, and pod information", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-SOCA-USER", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9._-]+$" }, "description": "SOCA username for authentication", "example": "john.doe" }, { "name": "X-SOCA-TOKEN", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "SOCA authentication token", "example": "abc123token456" }, { "name": "eks_cluster", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9._-]+$" }, "description": "Name of the EKS cluster", "example": "my-soca-cluster" }, { "name": "job_name", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" }, "description": "Name of the job to retrieve", "example": "simulation-job-001" }, { "name": "namespace", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 63, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "default": "default" }, "description": "Kubernetes namespace", "example": "default" } ], "responses": { "200": { "description": "Job details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "object", "required": [ "job_name", "status", "namespace", "cluster", "owner" ], "properties": { "job_name": { "type": "string", "example": "simulation-job-001" }, "status": { "type": "string", "enum": [ "Running", "Succeeded", "Failed", "Unknown" ], "example": "Running" }, "namespace": { "type": "string", "example": "default" }, "cluster": { "type": "string", "example": "my-soca-cluster" }, "owner": { "type": "string", "example": "john.doe" }, "created_time": { "type": "string", "format": "date-time", "nullable": true, "example": "2024-01-15T10:30:00Z" } } } } } } } }, "400": { "description": "Bad request - missing required parameters", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Missing required parameter: job_name" } } } } } }, "401": { "description": "Unauthorized - invalid authentication", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized: Verify if the IAM role is allowed to connect to cluster" } } } } } }, "403": { "description": "Forbidden - job does not belong to user", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This job does not seem to belong to you" } } } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Job not found in namespace default" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to retrieve job details" } } } } } } } }, "delete": { "operationId": "deleteEksJob", "tags": [ "Elastic Kubernetes Service (EKS)" ], "summary": "Delete an existing EKS job", "description": "Deletes an EKS job from the specified cluster and namespace. Only the job owner can delete their jobs.", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-SOCA-USER", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9._-]+$" }, "description": "SOCA username for authentication", "example": "john.doe" }, { "name": "X-SOCA-TOKEN", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "SOCA authentication token", "example": "abc123token456" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "eks_cluster", "job_name" ], "properties": { "eks_cluster": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9._-]+$", "description": "Name of the EKS cluster where the job is running", "example": "my-soca-cluster" }, "job_name": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "description": "Name of the job to delete", "example": "simulation-job-001" }, "namespace": { "type": "string", "minLength": 1, "maxLength": 63, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "default": "default", "description": "Kubernetes namespace where the job is located", "example": "default" } } } } } }, "responses": { "200": { "description": "Job deleted successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Job 'simulation-job-001' deleted successfully." } } } } } }, "400": { "description": "Bad request - missing required parameters", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Missing required parameter: job_name" } } } } } }, "401": { "description": "Unauthorized - invalid authentication or insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized: Verify if the IAM role is allowed to connect to cluster" } } } } } }, "403": { "description": "Forbidden - job does not belong to user", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This job does not seem to belong to you" } } } } } }, "404": { "description": "Job not found in the specified namespace", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Job simulation-job-001 not found in namespace default" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to delete job" } } } } } } } } }, "/api/containers/eks/jobs": { "get": { "operationId": "listEksJobs", "tags": [ "Elastic Kubernetes Service (EKS)" ], "summary": "List all EKS jobs owned by the current user", "description": "Retrieves a list of all EKS jobs owned by the authenticated user across tagged EKS clusters", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-SOCA-USER", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9._-]+$" }, "description": "SOCA username for authentication", "example": "john.doe" }, { "name": "X-SOCA-TOKEN", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "SOCA authentication token", "example": "abc123token456" }, { "name": "cluster", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9._-]+$" }, "description": "Name of the EKS cluster to query", "example": "my-soca-cluster" }, { "name": "namespace", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 63, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "default": "default" }, "description": "Kubernetes namespace to search in", "example": "default" } ], "responses": { "200": { "description": "Jobs retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "object", "additionalProperties": { "type": "object", "required": [ "metadata", "status", "pod_ips", "images", "eks_cluster" ], "properties": { "metadata": { "type": "object", "properties": { "name": { "type": "string", "example": "simulation-job-001" }, "namespace": { "type": "string", "example": "default" } } }, "status": { "type": "object", "properties": { "active": { "type": "integer", "minimum": 0, "example": 1 } } }, "pod_ips": { "type": "array", "items": { "type": "string", "format": "ipv4" }, "example": [ "10.0.1.100" ] }, "images": { "type": "array", "items": { "type": "string" }, "example": [ "nginx:latest" ] }, "eks_cluster": { "type": "string", "example": "my-soca-cluster" } } }, "example": { "job-uid-123": { "metadata": { "name": "simulation-job-001", "namespace": "default" }, "status": { "active": 1 }, "pod_ips": [ "10.0.1.100" ], "images": [ "nginx:latest" ], "eks_cluster": "my-soca-cluster" } } } } } } } }, "400": { "description": "Bad request - missing required parameters", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Missing required parameter: cluster" } } } } } }, "401": { "description": "Unauthorized - invalid authentication", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized: Verify if the IAM role is allowed to connect to cluster" } } } } } }, "404": { "description": "Namespace not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Namespace not found on your EKS cluster" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Error listing jobs across clusters" } } } } } } } } }, "/api/scheduler/queue": { "post": { "operationId": "createQueue", "tags": [ "PBS Pro Scheduler" ], "summary": "POST /api/scheduler/queue", "description": "POST operation for /api/scheduler/queue", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-SOCA-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin" }, { "name": "X-SOCA-TOKEN", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA authentication token", "example": "abc123token" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$", "minLength": 1, "maxLength": 50, "description": "Name of the queue to create", "example": "my-queue" }, "type": { "type": "string", "enum": [ "ondemand", "alwayson" ], "description": "Type of queue (ondemand or alwayson)", "example": "ondemand" } } } } } }, "responses": { "200": { "description": "Queue created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Queue my-queue created" } } } } } }, "400": { "description": "Missing parameters or invalid queue type" }, "401": { "description": "Authentication required" }, "403": { "description": "Admin access required" }, "409": { "description": "Queue already exists" }, "500": { "description": "PBS scheduler error" } } }, "delete": { "operationId": "deleteQueue", "tags": [ "PBS Pro Scheduler" ], "summary": "DELETE /api/scheduler/queue", "description": "DELETE operation for /api/scheduler/queue", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-SOCA-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin" }, { "name": "X-SOCA-TOKEN", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA authentication token", "example": "abc123token" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$", "minLength": 1, "maxLength": 50, "description": "Name of the queue to delete", "example": "my-queue" } } } } } }, "responses": { "200": { "description": "Queue deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Queue my-queue deleted" } } } } } }, "400": { "description": "Missing queue name parameter" }, "401": { "description": "Authentication required" }, "403": { "description": "Admin access required" }, "404": { "description": "Queue does not exist" }, "500": { "description": "PBS scheduler error" } } } }, "/api/scheduler/queues": { "get": { "operationId": "getQueues", "tags": [ "PBS Pro Scheduler" ], "summary": "GET /api/scheduler/queues", "description": "GET operation for /api/scheduler/queues", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-SOCA-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin" }, { "name": "X-SOCA-TOKEN", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA authentication token", "example": "abc123token" } ], "responses": { "200": { "description": "List of queues retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$" }, "example": [ "normal", "high", "low", "gpu" ] } } } } } }, "401": { "description": "Authentication required" }, "500": { "description": "PBS scheduler error or backend failure" } } } } }, "components": { "securitySchemes": { "socaAuth": { "type": "apiKey", "in": "header", "name": "X-SOCA-USER", "description": "SOCA username for authentication" }, "socaToken": { "type": "apiKey", "in": "header", "name": "X-SOCA-TOKEN", "description": "SOCA authentication token" } } }, "security": [ { "socaAuth": [], "socaToken": [] } ] }