> This page is for Self-Hosted, version v3.0 (default). > For other versions, use one of these documentation indexes: > - v3.0 (default): https://docs.nvidia.com/run-ai/self-hosted/v3.0/llms.txt > - v2.26: https://docs.nvidia.com/run-ai/self-hosted/v2.26/llms.txt > - v2.25: https://docs.nvidia.com/run-ai/self-hosted/v2.25/llms.txt > - v2.24: https://docs.nvidia.com/run-ai/self-hosted/v2.24/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/run-ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/run-ai/_mcp/server. # Get a policy. [experimental] GET http://localhost:8080/api/v1/policies/{PolicyId} Retrieve policy details by id, including both the declared rules and the effective rules. Reference: https://docs.nvidia.com/run-ai/self-hosted/reference/rest-api/endpoints/policies/policy/get-gvk-policy ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication ## Request ### Path parameters - `PolicyId` (string, required) — The unique identifier for the policy. ## Response ### 200 The requested policy. - `workloadType` (GVK, required) — Specifies the Group, Version, and Kind (GVK) of the Kubernetes resource that defines the workload. - `scope` (enum, required) - Allowed values: `system`, `tenant`, `cluster`, `department`, `project` - `id` (string, required) — The unique identifier for the policy. - `createdBy` (string, required) — Identifier of the user who created the policy. - `createdAt` (datetime, required) — The timestamp for when the policy was created. - `updatedBy` (string, required) — Identifier of the user who last updated the policy. - `updatedAt` (datetime, required) — The timestamp for when the policy was last updated. - `description` (string, optional) — A description of the policy. - `clusterId` (string, optional, nullable) — The id of the cluster the policy applies to. Required when the scope is cluster. - `departmentId` (string, optional, nullable) — The id of the department the policy applies to. Required when the scope is department. - `projectId` (string, optional, nullable) — The id of the project the policy applies to. Required when the scope is project. - `rules` (list of PolicyRule, optional) — The rules declared on this policy. Each rule targets a field in the workload spec and constrains its allowed values through its enforcements. - `effectiveRules` (list of GetGvkPolicyRespEffectiveRulesItems, optional) — The merged rule set in effect for this policy, including rules inherited from broader scopes (cluster, then department, then project). Each entry adds the sourceOfRule indicating where the rule was defined. Returned in responses only; not accepted in requests. - `status` (PolicyStatus, optional, nullable) — Configuration issues detected by the server for this policy. Returned in responses only; not accepted in requests. - `breakdown` (GetGvkPolicyRespBreakdown, optional, nullable) — The detailed breakdown, keyed into per-field variations and per-spec-selector details. ## Errors ### 400 Bad Request Error Bad request. - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ### 401 Unauthorized Error Unauthorized - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ### 403 Forbidden Error Forbidden - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ### 404 Not Found Error The specified resource was not found - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ### 503 Service Unavailable Error unexpected error - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ## Types ### GVK Specifies the Group, Version, and Kind (GVK) of the Kubernetes resource that defines the workload. - `version` (string, required) — The API version of the resource within the specified group. - `kind` (string, required) — The type of Kubernetes resource being referenced. - `group` (string, optional, nullable) — The API group of the Kubernetes resource. Empty string for core resources like Pod. ### PolicyRule A single policy rule. It combines the rule's identity (the field it targets, along with the spec selector, optional item selector, and selector parameters) with its enforcements (the behavior that constrains the field's allowed values). - `field` (string, required) — The unique name of the field. - `specSelector` (string, required) — The unique name of the spec selector - `enforcements` (list of PolicyRuleEnforcement, required) — The set of enforcements that define the rule's behavior. Each enforcement pairs an enforcement type with its value, and multiple enforcements may combine on a single rule to constrain the targeted field. - `itemSelector` (string, optional, nullable) — The name of the item selector that picks specific items of an itemized field. Omit for non-itemized fields. - `selectorParams` (map from string to any, optional) — The parameter values supplied to the spec selector and item selector at evaluation time, as a key-value map. - `allowOverride` (boolean, optional, nullable) — when false, a child scope cannot override this rule. default to false. ### GetGvkPolicyRespEffectiveRulesItems The origin of an effective rule. Identifies the scope at which the rule was defined and the matching project, department, or cluster id. Set by the server on effective rules in responses only; leave empty in requests. - `field` (string, required) — The unique name of the field. - `specSelector` (string, required) — The unique name of the spec selector - `enforcements` (list of PolicyRuleEnforcement, required) — The set of enforcements that define the rule's behavior. Each enforcement pairs an enforcement type with its value, and multiple enforcements may combine on a single rule to constrain the targeted field. - `sourceOfRule` (SourceOfRule, required) — This field is used by the system along with effective rules, in order to specify the org unit from which this effective rule has been derived. It should be left empty when sending apply policy requests. - `itemSelector` (string, optional, nullable) — The name of the item selector that picks specific items of an itemized field. Omit for non-itemized fields. - `selectorParams` (map from string to any, optional) — The parameter values supplied to the spec selector and item selector at evaluation time, as a key-value map. - `allowOverride` (boolean, optional, nullable) — when false, a child scope cannot override this rule. default to false. ### PolicyStatus Configuration issues detected by the server for the policy, along with its current phase. - `phase` (enum, optional) — The current phase of the policy. Supported values include: - Ready: The policy is fully validated, and all rules are successfully applied to the workload. - PendingUpdate: Configuration components (e.g., specSelector, itemSelector) have changed. The policy is awaiting validation to ensure the full rule set remains functional; this validation occurs the next time the policy is applied. - Degraded: One or more policy rules cannot be applied due to recent configuration changes. While the policy remains active, some rules may be ignored during enforcement. - Allowed values: `Ready`, `PendingUpdate`, `Degraded` - `issues` (list of string, optional) — The list of configuration issues detected for the policy. ### GetGvkPolicyRespBreakdown The detailed breakdown, keyed into per-field variations and per-spec-selector details. - `fields` (map from string to list of BreakdownFieldVariation, optional) — The detailed breakdown of fields, keyed by field name. Each field maps to the list of its variations across the requested spec selectors and item selectors. - `specSelectors` (map from string to BreakdownSpecSelector, optional) — The detailed breakdown of spec selectors, keyed by spec-selector name. ### PolicyRuleEnforcement A single enforcement on a policy rule. Exactly one enforcement type is expressed per object (for example set, default, required, blocked, options, match, or one of the grouped range, length, elements, items, or quantityRange constraints); combine multiple enforcement objects on a rule to apply several constraints to the same field. ### SourceOfRule This field is used by the system along with effective rules, in order to specify the org unit from which this effective rule has been derived. It should be left empty when sending apply policy requests. - `scope` (enum, required) - Allowed values: `system`, `tenant`, `cluster`, `department`, `project` - `projectId` (integer, optional) — The id of the project. - `departmentId` (string, optional) — The id of the department. - `clusterId` (string, optional) — The id of the cluster. - `isFallback` (boolean, optional) — source of this rule is the fallback policy ### BreakdownFieldVariation A single variation of a field in the breakdown: the spec selectors it appears under, how it is read and written (formatter details or a direct specRef), its data type, and the item-selector queries that apply to it. - `specSelectors` (list of string, optional) — The spec selectors under which this variation of the field appears. - `formatter` (BreakdownFormatter, optional) — The formatter details for a field in the breakdown: either the name of the built-in formatter used, or the resolved getExpr/setExpr, arrayKey, and argument type/enum information. - `specRef` (string, optional) — A direct dotted path into the workload spec, used in place of a formatter for simple fields. - `type` (enum, optional) — The data type of the field. - Allowed values: `string`, `boolean`, `integer`, `number`, `quantity`, `ipaddress`, `integers`, `numbers`, `strings`, `namesArray`, `object` - `itemSelectors` (map from string to BreakdownItemSelector, optional) — The item selectors that apply to the field, keyed by item-selector name, with each value containing the item selector's JQ query and argument metadata. - `possibleEnforcements` (list of enum, optional) — The enforcement types that may be applied to this variation of the field. Derived from the field's data type, with `items` added when the field is itemized (has an itemSelector). - Allowed values: `set`, `default`, `required`, `blocked`, `match`, `options`, `length`, `range`, `quantityRange`, `elements`, `items` ### BreakdownSpecSelector The details of a single spec selector in the breakdown: its description, JQ query, and the type and enum information for any arguments referenced by the query. - `description` (string, optional) — A free-text description of the element. - `query` (string, optional) — The JQ query used to select a subtree of the workload spec. Consult https://jqlang.org/manual/ for further info. - `argsInfo` (map from string to enum, optional) — The data type of each argument referenced by the JQ expression as \$ARGS.named.\. - Allowed values: `string`, `boolean`, `integer`, `number`, `quantity`, `ipaddress`, `integers`, `numbers`, `strings`, `namesArray`, `object` - `argsEnum` (map from string to list of string, optional) — The allowed values for each string-typed argument referenced by the JQ expression as \$ARGS.named.\. Up to 100 values per argument. - `dependency` (SpecSelectorDependency, optional) — Declares that this spec selector depends on a parent path existing. The engine will ensure the element path exists before running SET/DEFAULT actions that target this selector. ### PolicyEnforcementSet - `set` (map from string to any, optional) — Enforces the value of the field. ### PolicyEnforcementDefault - `default` (map from string to any, optional) — Sets the value of the field when the user does not supply one. ### PolicyEnforcementRequired - `required` (boolean, optional, nullable, default: false) — Requires the field to have a value, supplied either in the submission or by a policy default. ### PolicyEnforcementBlocked - `blocked` (boolean, optional, nullable, default: false) — Prevents the field from being assigned any value. Inverse of "required". ### PolicyEnforcementLength - `length` (PolicyEnforcementLengthLength, optional, nullable) — Enforces the field's length (character count for strings, element count for slices, arrays, and maps) to fall within the inclusive range [min, max]. At least one of `min`/`max` must be specified. ### PolicyEnforcementOptions - `options` (list of string, optional, nullable) — Restricts the value of the field to one of the listed options. ### PolicyEnforcementMatch - `match` (string, optional, nullable) — Requires the value of the field to match the regular expression. ### PolicyEnforcementRange - `range` (PolicyEnforcementRangeRange, optional, nullable) — Enforces a numeric value to fall within the inclusive range [min, max], optionally restricted to increments of `step` starting from `min`. ### PolicyEnforcementElements - `elements` (PolicyEnforcementElementsElements, optional, nullable) — Enforces the number of elements in an array field to fall within the inclusive range [min, max]. At least one of `min`/`max` must be specified. ### PolicyEnforcementItems - `items` (PolicyEnforcementItemsItems, optional, nullable) — Enforces the number of items produced by a field's itemSelector to fall within the inclusive range [min, max]. At least one of `min`/`max` must be specified. Applies only to fields that declare itemSelectors. ### PolicyEnforcementQuantityRange - `quantityRange` (PolicyEnforcementQuantityRangeQuantityRange, optional, nullable) — Enforces a Kubernetes resource quantity to fall within the inclusive range [min, max], optionally restricted to increments of `step` starting from `min`. All bounds must be valid Kubernetes quantities such as 100m, 1Gi, or 500Mi. ### BreakdownFormatter The formatter details for a field in the breakdown: either the name of the built-in formatter used, or the resolved getExpr/setExpr, arrayKey, and argument type/enum information. - `builtin` (string, optional, nullable) — The name of the built-in formatter, if used. - `setExpr` (string, optional, nullable) — The JQ expression used to write the field value into the workload spec. Consult https://jqlang.org/manual/ for further info. - `getExpr` (string, optional, nullable) — The JQ expression used to read the field value from the workload spec. Consult https://jqlang.org/manual/ for further info. - `arrayKey` (FormatterArrayKey, optional, nullable) — The unique key per item for an itemized field, provided as an argName with an optional specRef. - `argsInfo` (map from string to enum, optional) — The data type of each argument referenced by the JQ expression as \$ARGS.named.\. - Allowed values: `string`, `boolean`, `integer`, `number`, `quantity`, `ipaddress`, `integers`, `numbers`, `strings`, `namesArray`, `object` - `argsEnum` (map from string to list of string, optional) — The allowed values for each string-typed argument referenced by the JQ expression as \$ARGS.named.\. Up to 100 values per argument. ### BreakdownItemSelector The details of a single item selector in the breakdown: its JQ query, and the type and enum information for any arguments referenced by the query. - `query` (string, optional) — The JQ query used to filter items of an itemized field. Consult https://jqlang.org/manual/ for further info. - `argsInfo` (map from string to enum, optional) — The data type of each argument referenced by the JQ expression as \$ARGS.named.\. - Allowed values: `string`, `boolean`, `integer`, `number`, `quantity`, `ipaddress`, `integers`, `numbers`, `strings`, `namesArray`, `object` - `argsEnum` (map from string to list of string, optional) — The allowed values for each string-typed argument referenced by the JQ expression as \$ARGS.named.\. Up to 100 values per argument. ### SpecSelectorDependency Declares that this spec selector depends on a parent path existing. The engine will ensure the element path exists before running SET/DEFAULT actions that target this selector. - `specSelector` (string, optional, nullable) — Optional parent spec selector that provides iteration context. When set, the element path is created relative to each result of the parent selector. When omitted, element is relative to the workload root. - `path` (string, optional) — Dot-separated path to ensure exists below the parent. Example: "template.metadata" creates both .template and .template.metadata if missing. ### PolicyEnforcementLengthLength Enforces the field's length (character count for strings, element count for slices, arrays, and maps) to fall within the inclusive range [min, max]. At least one of `min`/`max` must be specified. - `min` (integer, optional, nullable) — Enforces the minimum length. - `max` (integer, optional, nullable) — Enforces the maximum length. ### PolicyEnforcementRangeRange Enforces a numeric value to fall within the inclusive range [min, max], optionally restricted to increments of `step` starting from `min`. - `min` (double, optional, nullable) — Enforces the minimum numeric value of the field. - `max` (double, optional, nullable) — Enforces the maximum numeric value of the field. - `step` (double, optional, nullable) — Restricts the field value to specific numeric increments starting from `min` (or from 0 when `min` is absent). Must be greater than 0. ### PolicyEnforcementElementsElements Enforces the number of elements in an array field to fall within the inclusive range [min, max]. At least one of `min`/`max` must be specified. - `min` (integer, optional, nullable) — Enforces the minimum number of elements. - `max` (integer, optional, nullable) — Enforces the maximum number of elements. ### PolicyEnforcementItemsItems Enforces the number of items produced by a field's itemSelector to fall within the inclusive range [min, max]. At least one of `min`/`max` must be specified. Applies only to fields that declare itemSelectors. - `min` (integer, optional, nullable) — Enforces the minimum number of items. - `max` (integer, optional, nullable) — Enforces the maximum number of items. ### PolicyEnforcementQuantityRangeQuantityRange Enforces a Kubernetes resource quantity to fall within the inclusive range [min, max], optionally restricted to increments of `step` starting from `min`. All bounds must be valid Kubernetes quantities such as 100m, 1Gi, or 500Mi. - `min` (string, optional, nullable) — Enforces the minimum quantity value of the field. - `max` (string, optional, nullable) — Enforces the maximum quantity value of the field. - `step` (string, optional, nullable) — Restricts the field value to specific quantity increments starting from `min` (or from 0 when `min` is absent). ### FormatterArrayKey The unique key per item for an itemized field, provided as an argName with an optional specRef. - `argName` (string, required) — The name of the argument that supplies the unique key value per item. - `specRef` (string, optional, nullable) — An optional direct dotted path into the workload spec that locates the key value for each item. ## Examples **Response** ```json { "workloadType": { "version": "v1", "kind": "Deployment", "group": "apps" }, "scope": "system", "id": "string", "createdBy": "string", "createdAt": "2024-01-15T09:30:00Z", "updatedBy": "string", "updatedAt": "2024-01-15T09:30:00Z", "description": "a short description of the policy", "clusterId": "string", "departmentId": "string", "projectId": "string", "rules": [ { "field": "containerPort", "specSelector": "containerByName", "enforcements": [ { "set": { "containerPort": 1234, "protocol": "TCP" } } ], "itemSelector": "string", "selectorParams": { "containerName": "my-container" }, "allowOverride": true } ], "effectiveRules": [ { "field": "containerPort", "specSelector": "containerByName", "enforcements": [ { "set": { "containerPort": 1234, "protocol": "TCP" } } ], "sourceOfRule": { "scope": "project", "projectId": 3 }, "itemSelector": "string", "selectorParams": { "containerName": "my-container" }, "allowOverride": true } ], "status": { "phase": "Ready", "issues": [ "configuration-issue-1", "configuration-issue-2" ] }, "breakdown": { "fields": {}, "specSelectors": {} } } ``` **SDK Code** ```python import requests url = "http://localhost:8080/api/v1/policies/PolicyId" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'http://localhost:8080/api/v1/policies/PolicyId'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "http://localhost:8080/api/v1/policies/PolicyId" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("http://localhost:8080/api/v1/policies/PolicyId") http = Net::HTTP.new(url.host, url.port) request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("http://localhost:8080/api/v1/policies/PolicyId") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'http://localhost:8080/api/v1/policies/PolicyId', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("http://localhost:8080/api/v1/policies/PolicyId"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "http://localhost:8080/api/v1/policies/PolicyId")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```