github.com/inspektor-gadget/inspektor-gadget@v0.28.1/docs/core-concepts/custom-resources.md (about)

     1  ---
     2  title: Custom Trace Resource
     3  weight: 200
     4  description: >
     5    Basic usage of the Trace resource
     6  ---
     7  
     8  > ⚠️ We are currently removing the Trace resource and using a [gRPC
     9  > API](../reference/grpc.md) instead. Once done, the Trace resource will be
    10  > deprecated.
    11  
    12  Inspektor Gadget uses a custom `Trace` resource to communicate between the
    13  endpoints and the `gadget` DaemonSet running on the cluster. These
    14  resources are used to control which gadgets run in a given cluster.
    15  
    16  This is the basic format of this resource:
    17  
    18  ```yaml
    19  apiVersion: gadget.kinvolk.io/v1alpha1
    20  kind: Trace
    21  metadata:
    22    name: trace-name
    23    namespace: gadget
    24  spec:
    25    node: node-name
    26    gadget: gadget-name
    27    filter:
    28      namespace: namespace-name
    29      podname: podname-name
    30    runMode: Manual
    31    outputMode: Status
    32  ```
    33  
    34  Some gadgets work at the node level, while others support specific filters,
    35  like `namespace`, `podname`, `labels`, and so on.
    36  
    37  The possible values for `outputMode` also depend on the gadget. The
    38  `seccomp` gadget, for example, can create seccomp policies as an external
    39  resource when `ExternalResource` is selected. If `outputMode` is set to
    40  `Status`, the output of the trace will be stored in the status field of the
    41  trace resource. 
    42  
    43  See the corresponding [gadgets specs](../crds/gadgets/_index.md) to
    44  find out what's available.
    45  
    46  Note that **all traces should be created in the `gadget` namespace**. And,
    47  for now, the node name needs to be explicitly set in the trace.
    48  
    49  ### Setting the `Trace` operation
    50  
    51  Once the `Trace` resource is created, the `gadget.kinvolk.io/operation`
    52  field is used to control when the gadget should run.
    53  
    54  Some gadgets accept a single operation that triggers a run and stores the
    55  output. Other gadgets need to be started and stay running until they get
    56  stopped later on to obtain the output.
    57  
    58  To control whether a gadget should get started or stopped, annotate the
    59  corresponding trace resource with
    60  `gadget.kinvolk.io/operation=<operation-name>`
    61  
    62  Note that the trace controller will remove the annotation after it has
    63  processed it. So, if you find yourself having to forcefully overwrite the
    64  value of this field, it means that the trace controller is having trouble
    65  processing your `Trace` resource.
    66  
    67  ### Using `Trace` resources from the command line
    68  
    69  It's possible to create and interact with the `Trace` resources directly
    70  from the command line, using `kubectl apply` with a YAML file containing
    71  the specified trace.
    72  
    73  After creating the resource, the corresponding operation can be set with
    74  `kubectl annotate`, as in the following example:
    75  
    76  ```bash
    77  $ kubectl annotate -n gadget trace/trace-name gadget.kinvolk.io/operation=start
    78  ```
    79  
    80  ### Using `Trace` resources from graphical interfaces
    81  
    82  Graphical interfaces that interact with Kubernetes, can integrate with
    83  Inspektor Gadget by creating and modifying `Trace` resources in the
    84  `gadget` namespace, and following the corresponding gadget specifications.
    85  
    86  Gadgets can then be controlled by annotating the
    87  `gadget.kinvolk.io/operation` field with the corresponding operation.
    88  
    89  As an example, see the [biolatency
    90  plugin](https://github.com/kinvolk/lokomotive-web-ui/blob/main/plugins/biolatency/src/index.tsx)
    91  implementation for Headlamp.
    92  
    93  ### Interacting with traces using the `kubectl-gadget` CLI
    94  
    95  The `kubectl-gadget` plugin may create, annotate and delete `Trace`
    96  resources as necessary to interact with the `gadget` DaemonSet running on
    97  the nodes. This is mostly transparent to the user, who will just get the
    98  results through the command-line.