Applying Custom Policies
The Policy Engine lets users define custom validation and modification rules using TypeScript. It helps ensure compliance, security, and consistency by enforcing rules and dynamically updating manifests before deployment.
Validation Policies
Validation policies ensure that only compliant configurations are deployed. These policies evaluate Truefoundry manifests and prevent deployments that do not meet specific conditions. Some common use cases include:
- Enforcing readiness and liveness probes for all production services.
- Enforcing on-demand instance on production environments for better reliability
- Enforcing auto shutdown for all dev services.
Here is a sample policy which enforces auto-shutdown for all services deployed in dev environments
Mutation Policies
Mutation policies let you automatically modify Kubernetes manifests before they’re applied to the cluster. You can define custom rules by writing code to change these manifests based on your needs—no need to use Kustomize.
Common use cases include:
- Setting node affinity for certain workloads like SSH servers or notebooks
- Adding default secrets, volume mounts, or environment variables to services and jobs
- Updating image prefixes to match internal repository setups
These policies run one after another, in a specific order. Policies with lower order values are applied first.
Here is a sample mutation policy which mutates the registry for the images to private jfrog repository.
Both validation and mutation policies are executed in a sandbox environment before deployment to ensure secure and isolated execution.
Policy Context
The policy context provides additional information that can be used to enforce more sophisticated policies.
Environment
The environment
field contains the deployment environment manifest,
which includes information like whether it’s a production environment or whether it’s optimized for Cost or Availability
This allows you to enforce different policies based on the environment type.
Created By User
The createdByUser
field in the context provides information about who initiated
the deployment. This is useful for enforcing policies based on the deployment source.
For example, you might want to ensure that production deployments are only made through service accounts for better security and audit trails.
Here’s an example policy that enforces this:
Active Deployment
The activeDeployment
field contains the manifest of the last successful deployment.
This is useful for policies that need to compare new deployments with the last known good state. For example, you might want to prevent changes to critical fields like image URIs after a successful deployment to maintain stability.
Creating a policy
Policies must be written in TypeScript. To write and test your policy code, refer to this repository: https://github.com/truefoundry/tfy-typescript-policy
- Write your policy logic in
src/policy.ts
. - Import required models from
src/models.ts
.
Use type definitions from src/types.ts
to ensure type-safe code.
Test your policy locally using:
You can find policy code examples for common use cases in this folder: https://github.com/truefoundry/tfy-typescript-policy/tree/main/examples
Note: When creating/updating your policy, only provide the contents of policy.ts in the Policy Code input field.
Registering Your Policy on Truefoundry
After writing your policy code, you can register your policy on Truefoundry by following these steps:
1. Enter Policy Details
Provide the name and description of the policy.
2. Select Policy Action
-
Validate: Ensures manifests meet certain conditions.
-
Mutate: Modifies manifests before applying them.
Mutate policies have an order associated that determines their execution order.
3. Choose Policy Mode
- Audit: Logs policy executions but does not block deployments. Ideally when creating a policy, users should put it in
- Enforce: Blocks deployments if the policy evaluation fails.
- Disabled: The policy is ignored.
4. TypeScript Code:
Paste the typescript code that you wrote in previous step.
5. Define Entities
Specify the resource types the policy should apply to. (service, job, ssh-server etc)
6. Set Filters
Use Clusters, Environments, and Workspaces to filter applicable manifests. [by default it applies to all manifests]
Filters expect the name (not FQN) of workspaces, environments, and clusters.
Here is how it looks on UI:
You can find all Policies registered and see their specific runs:
You can also check the diff for a mutation policy also: