create a private hook

Function

CreatePrivateHook

Create a private hook with an initial default version. When creating a private hook, you need to create an initial default version at the same time. An empty private hook cannot be created.

The private hook takes effect when triggering the stack deployment only after the configuration is set. The stack uses the default version of the private hook. If no configuration is specified when a private hook is created, the private hook does not take effect during stack deployment. You can update the configuration by calling UpdatePrivateHook API.

Currently, Stack Service APIs that support hook policy validation are as follows:

CreateExecutionPlan

ApplyExecutionPlan

CreateStack

DeployStack

ContinueDeployStack

DeleteStack

DeleteStackEnhanced
The version specified when the private hook is created is the initial default version.
If a private hook with the same name already exists in the current domain_id + region, 409 is returned.
The version must follow the Semantic Version and is customized by the user.
RFS performs validations on private hooks, such as file size checks and policy document syntax validation. If any errors are found, the creation of the hook will fail.
Currently, our system exclusively facilitates pre-deployment validation for stacks; in-stack deployment checks are not yet supported. If the pre-deployment validation is passed, the deployment is continued. Otherwise, the deployment stops and stack events are recorded.
Only support policy templates written in Rego (https://www.openpolicyagent.org/docs/latest/policy-language/) and identified by the OPA open source engine. (Users can use policy_uri or policy_body to specify the policy file content.)
Use hook_result of the object type as the decision result. The name of the package where the hook_result is located must be policy. The format of hook_result is as follows:
```
hook_result := {
  "is_passed": Bool,
  "err_msg": String,
}
```
is_passed is mandatory and err_msg is optional. RFS queries the policy.hook_result[is_passed] to determine whether the policy verification is passed.
- If the value of policy.hook_result[is_passed] is true, the policy passes the verification and RFS will continue to deploy stacks.
- If the value of policy.hook_result[is_passed] is false, the policy fails to be verified. In this case, RFS stops deploying stacks and records the stack event information. The information content is policy.hook_result[err_msg]. If err_msg is not set, the stack event information is the default error information (Validate private hook failed).
- If policy.hook_result is not used, the policy does not take effect and the RFS continues to deploy stacks.
The policy template does not support data obtaining by invoking APIs of other services, network access in any form, user-defined functions or methods in any form, local file reading, or system operations.

The policy template syntax for a private hook is as follows:

package policy

import rego.v1

hook_result := {
  "is_passed": input.message == "world",
  "err_msg": "The error msg when private hook is not passed the validation",
}

URI

POST /v1/private-hooks

Request Parameters

**Table 1** Request header parameters
Parameter	Mandatory	Type	Description
Client-Request-Id	Yes	String	Unique request ID. It is specified by a user and is used to locate a request. UUID is recommended.

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
hook_name	Yes	String	Private hook name. The name is unique within its domain (domain_id) and region. It can contain Chinese characters, uppercase and lowercase letters, digits, underscores (_), and hyphens (-). The first character must be a Chinese or English character. It is case sensitive. We recommend users to use a three-part namespace for naming: {custom-hook-name}-{hook application context}-hook.
hook_version	Yes	String	Private hook version. The version number follows the Semantic Version and is customized by the user.
hook_description	No	String	Description of a private hook. It can be used by customers to identify their own private hooks. You can update the description of the private hook by calling UpdatePrivateHook API.
hook_version_description	No	String	Description of the private hook version. It can be used by users to identify and manage private hook versions. Note: The private hook version is immutable, so the description cannot be updated. If it needs to be updated, please delete private hook version and rebuild it.
configuration	No	configuration object	Private hook configuration. It can specify the target stack where the private hook takes effect and the behavior of the stack after the private hook verification fails. You can use UpdatePrivateHook API to update private hook configuration.
policy_uri	No	String	OBS address of the policy file. The content must be written in the Rego language, which is recognizable by the open-source OPA (Open Policy Agent) engine, as described in the documentation at https://www.openpolicyagent.org/docs/latest/policy-language/. Ensure that the OBS address is located in the same region as the RFS. The policy file can be a single file or a .zip package. A single file must end with .rego. A .zip package must end with .zip. The policy file verification requirements are as follows: Files must be UTF8 encoded During creation, validations are performed for size, format, syntax, etc. The policy file must be in UTF-8 encoding format. The size of a single file or compressed package before and after decompression must be less than 1 MB. The number of files in the compressed package cannot exceed 100. The maximum length of file paths in the compressed package is 2048 characters. The maximum length of the policy file name in the compressed package is 255 bytes. Either policy_uri or policy_body must be specified.
policy_body	No	String	Policy content. The content must be written in the Rego language, which is recognizable by the open-source OPA (Open Policy Agent) engine, as described in the documentation at https://www.openpolicyagent.org/docs/latest/policy-language/. Either policy_uri or policy_body must be specified.

**Table 3** configuration
Parameter	Mandatory	Type	Description
target_stacks	No	String	Specifies the target stack where the private hook takes effect. The value can be NONE or ALL. NONE: Specifies that this private hook will not be applied to any stacks. ALL: Specifies that the private hook will be applied to all stacks under the account.
failure_mode	No	String	Specifies the behavior when the private hook validation fails. Valid values are FAIL or WARN. FAIL: Specifies that if this private hook validation fails, the stack will stop deploying, and the stack status will be updated to DEPLOYMENT_FAILED. WARN: Specifies that if this private hook validation fails, only a warning message will be displayed through the stack events, but it will not affect the deployment of the stack.

Response Parameters

Status code: 201

**Table 4** Response body parameters
Parameter	Type	Description
hook_id	String	Unique ID of a private hook. It is an UUID generated by RFS when a private hook is created. Private hook names are unique only at one specific time, so you can create a private hook named helloWorld and another private hook with the same name after deleting the first one. For parallel development in a team, users may want to ensure that the private hook they operate is the one created by themselves, not the one with the same name created by other teammates after deleting the previous one. Therefore, they can use this ID for strong matching. RFS ensures that the ID of each private hook is different and does not change with updates. If the hook_id value is different from the current private hook ID, 400 is returned.

Status code: 400

**Table 5** Response body parameters
Parameter	Type	Description
error_code	String	Response code
error_msg	String	Response message

Status code: 401

**Table 6** Response body parameters
Parameter	Type	Description
error_code	String	Response code
error_msg	String	Response message

Status code: 403

**Table 7** Response body parameters
Parameter	Type	Description
error_code	String	Response code
error_msg	String	Response message

Status code: 409

**Table 8** Response body parameters
Parameter	Type	Description
error_code	String	Response code
error_msg	String	Response message

Status code: 429

**Table 9** Response body parameters
Parameter	Type	Description
error_code	String	Response code
error_msg	String	Response message

Status code: 500

**Table 10** Response body parameters
Parameter	Type	Description
error_code	String	Response code
error_msg	String	Response message

Example Requests

Create a private hook with an initial default version

POST https://{endpoint}/v1/private-hooks

{
  "hook_name" : "my-hello-world-hook-name",
  "hook_version" : "0.0.1",
  "policy_uri" : "https://my_hello_world_bucket.{region}.myhuaweicloud.com/policy.rego",
  "configuration" : {
    "target_stacks" : "NONE",
    "failure_mode" : "WARN"
  },
  "hook_description" : "my first private hook",
  "hook_version_description" : "my first private hook version"
}

Example Responses

Status code: 201

Private hook created successfully.

{
  "hook_id" : "1b15e005-bdbb-4bd7-8f9a-a09b6774b4b3"
}

Status Codes

Status Code	Description
201	Private hook created successfully.
400	Invalid request.
401	Authentication failed.
403	The user does not have the permission to call this API. The maximum number of private hook has been reached.
409	Creation requests conflict. The specified private hook already exists.
429	Too frequent requests.
500	Internal server error.