[Docs]: Functions Example in Docs

[vfarcic]

Problem Statement

It's not clear how to use functions based on https://kyverno.github.io/chainsaw/latest/jp/functions/.

Solution Description

Add a few examples to the docs.

Alternatives

No response

Additional Context

No response

Slack discussion

No response

Research

• I have searched other issues in this repository and mine is not recorded.

[shubham-cmyk]

@vfarcic We have some examples here.
https://github.com/kyverno/chainsaw/tree/main/testdata/e2e/examples

we can make a specific directory here functions to display the use of everyfunction :)

[vfarcic]

That would be great. What I'm looking for is an example of contains. I'm hoping that I could use it to validate whether an array contains specific entries. My arrays have tens or more entries and listing them all tends to be cumbersome.

[shubham-cmyk]

(contains($stdout, '[OK] All 16384 slots covered.')): true

complete test : https://github.com/OT-CONTAINER-KIT/redis-operator/blob/db14d1b018b2fd0f62485bd2f8bd9b376c81dc10/tests/e2e-chainsaw/v1beta2/nodeport/redis-cluster/chainsaw-test.yaml#L66

[vfarcic]

@shubham-cmyk Would that work without a script? I'm trying to add something like that to the assert manifest.

[shubham-cmyk]

assert manifest ?
why would you need a check on the assert manifest.

[eddycharly]

currently we generate the docs from the code... i will see if i can improve that in the jp lib, i agree this is a bit poor ;)

[shubham-cmyk]

i think we can.

[vfarcic]

Here's a manifest:

apiVersion: devopstoolkitseries.com/v1alpha1
kind: SQL
metadata:
  name: xyz
spec:
  claimRef:
    apiVersion: devopstoolkitseries.com/v1alpha1
    kind: SQLClaim
    name: my-db
  compositionRef:
    name: aws-postgresql
  compositionSelector:
    matchLabels:
      db: postgresql
      provider: aws
  compositionUpdatePolicy: Automatic
  id: my-db-aws
  parameters:
    size: medium
    version: "13.4"
  resourceRefs:
  - apiVersion: ec2.aws.upbound.io/v1beta1
    kind: InternetGateway
    name: my-db-aws
  - apiVersion: ec2.aws.upbound.io/v1beta1
    kind: MainRouteTableAssociation
    name: my-db-aws
  - apiVersion: ec2.aws.upbound.io/v1beta1
    kind: RouteTableAssociation
    name: my-db-aws-1a
  - apiVersion: ec2.aws.upbound.io/v1beta1
    kind: RouteTableAssociation
    name: my-db-aws-1b
  - apiVersion: ec2.aws.upbound.io/v1beta1
    kind: RouteTableAssociation
    name: my-db-aws-1c
  - apiVersion: ec2.aws.upbound.io/v1beta1
    kind: RouteTable
    name: my-db-aws
  - apiVersion: ec2.aws.upbound.io/v1beta1
    kind: Route
    name: my-db-aws
  - apiVersion: ec2.aws.upbound.io/v1beta1
    kind: SecurityGroupRule
    name: my-db-aws
  - apiVersion: ec2.aws.upbound.io/v1beta1
    kind: SecurityGroup
    name: my-db-aws
  - apiVersion: ec2.aws.upbound.io/v1beta1
    kind: Subnet
    name: my-db-aws-a
  - apiVersion: ec2.aws.upbound.io/v1beta1
    kind: Subnet
    name: my-db-aws-b
  - apiVersion: ec2.aws.upbound.io/v1beta1
    kind: Subnet
    name: my-db-aws-c
  - apiVersion: ec2.aws.upbound.io/v1beta1
    kind: VPC
    name: my-db-aws
  - apiVersion: kubernetes.crossplane.io/v1alpha1
    kind: ProviderConfig
    name: my-db-aws-sql
  - apiVersion: kubernetes.crossplane.io/v1alpha2
    kind: Object
    name: my-db-aws-secret
  - apiVersion: postgresql.sql.crossplane.io/v1alpha1
    kind: Database
    name: my-db-aws-db-01
  - apiVersion: postgresql.sql.crossplane.io/v1alpha1
    kind: Database
    name: my-db-aws-db-02
  - apiVersion: postgresql.sql.crossplane.io/v1alpha1
    kind: Database
    name: my-db-aws-db-03
  - apiVersion: postgresql.sql.crossplane.io/v1alpha1
    kind: ProviderConfig
    name: my-db-aws
  - apiVersion: rds.aws.upbound.io/v1beta1
    kind: Instance
    name: my-db-aws
  - apiVersion: rds.aws.upbound.io/v1beta1
    kind: SubnetGroup
    name: my-db-aws

I'd like to check that, among other things, that resource contains spec.resourceRefs[].kind: InternetGateway without having to specify all the items in spec.resourceRefs.

[shubham-cmyk]

apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: example
spec:
  steps:
  - try:
    # ...
    - assert:
        resource:
          apiVersion: v1
          kind: Deployment
          metadata:
            name: foo
          spec:
            (replicas > 3): true
    # ...

refer : https://kyverno.github.io/chainsaw/main/operations/assert/#usage-in-test

Would this example help

[eddycharly]

@vfarcic you can do something like this:

(contains(spec.resourceRefs[?kind == InternetGateway].[name], ['my-db-aws'])): true

It's called multiselect in jmespath term.

(you can do multiselect hash but harder to use because it uses : and conflicts with the yaml syntax unless the key is quoted)

[vfarcic]

Would something like the following be it?

apiVersion: devopstoolkitseries.com/v1alpha1
kind: SQL
metadata:
  labels:
    crossplane.io/claim-name: my-db
spec:
  claimRef:
    apiVersion: devopstoolkitseries.com/v1alpha1
    kind: SQLClaim
    name: my-db
  compositionRef:
    name: aws-postgresql
  compositionSelector:
    matchLabels:
      db: postgresql
      provider: aws
  compositionUpdatePolicy: Automatic
  id: my-db-aws
  parameters:
    size: medium
    version: "13.4"
  (contains(resourceRefs[?kind == InternetGateway].[name], ['my-db-aws'])): true
  resourceRefs:
  - apiVersion: ec2.aws.upbound.io/v1beta1
    kind: InternetGateway
    name: my-db-aws
  - apiVersion: ec2.aws.upbound.io/v1beta1
    kind: MainRouteTableAssociation
    name: my-db-aws
  - apiVersion: ec2.aws.upbound.io/v1beta1
    kind: RouteTableAssociation
    name: my-db-aws-1a

That one is throwing * spec.(contains(resourceRefs[?kind == InternetGateway].[name], ['my-db-aws'])): Invalid value: false: Expected value: true.

I left the existing resourceRef there as a reference. Without the contains line it works so the InternetGateway is definitely there.

[eddycharly]

(contains(resourceRefs[?kind == 'InternetGateway'].[name], ['my-db-aws'])) (needs quotes)

[eddycharly]

Tried it, with quotes it passes:

apiVersion: devopstoolkitseries.com/v1alpha1
kind: SQL
metadata:
  labels:
    crossplane.io/claim-name: my-db
spec:
  claimRef:
    apiVersion: devopstoolkitseries.com/v1alpha1
    kind: SQLClaim
    name: my-db
  compositionRef:
    name: aws-postgresql
  compositionSelector:
    matchLabels:
      db: postgresql
      provider: aws
  compositionUpdatePolicy: Automatic
  id: my-db-aws
  parameters:
    size: medium
    version: "13.4"
  (length(resourceRefs[?kind == 'InternetGateway'])): 1
  (contains(resourceRefs[?kind == 'InternetGateway'].[name], ['my-db-aws'])): true

chainsaw assert -r ./_resource.yaml -f ./_assert.yaml
Assertion(s) PASSED

[eddycharly]

@vfarcic there's a simpler and more elegant solution:

apiVersion: devopstoolkitseries.com/v1alpha1
kind: SQL
metadata:
  labels:
    crossplane.io/claim-name: my-db
spec:
  claimRef:
    apiVersion: devopstoolkitseries.com/v1alpha1
    kind: SQLClaim
    name: my-db
  compositionRef:
    name: aws-postgresql
  compositionSelector:
    matchLabels:
      db: postgresql
      provider: aws
  compositionUpdatePolicy: Automatic
  id: my-db-aws
  parameters:
    size: medium
    version: "13.4"
  (resourceRefs[?kind == 'InternetGateway']):
  - name: my-db-aws

[vfarcic]

That's the one I like the most. @eddycharly. It's easy to read than the previous example.

[eddycharly]

For reference grafana/tempo-operator#786 (comment)