sigs.k8s.io/cluster-api@v1.7.1/docs/book/src/clusterctl/plugins.md (about)

     1  # clusterctl Extensions with Plugins
     2  
     3  You can extend `clusterctl` with plugins, similar to `kubectl`. Please refer to the [kubectl plugin documentation](https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/) for more information, 
     4  as `clusterctl` plugins are implemented in the same way, with the exception of plugin distribution.
     5  
     6  ## Installing clusterctl plugins
     7  
     8  To install a clusterctl plugin, place the plugin's executable file in any location on your `PATH`.
     9  
    10  ## Writing clusterctl plugins
    11  
    12  No plugin installation or pre-loading is required. Plugin executables inherit the environment from the `clusterctl` binary. A plugin determines the command it implements based on its name. 
    13  For example, a plugin named `clusterctl-foo` provides the `clusterctl` foo command. The plugin executable should be installed in your `PATH`.
    14  
    15  Example plugin
    16  
    17  ```bash
    18  #!/bin/bash
    19  
    20  # optional argument handling
    21  if [[ "$1" == "version" ]]
    22  then
    23  echo "1.0.0"
    24  exit 0
    25  fi
    26  
    27  # optional argument handling
    28  if [[ "$1" == "example-env-var" ]]
    29  then
    30      echo "$EXAMPLE_ENV_VAR"
    31      exit 0
    32  fi
    33  
    34  echo "I am a plugin named clusterctl-foo"
    35  ```
    36  
    37  ### Using a plugin
    38  To use a plugin, make the plugin executable:
    39  
    40  ```bash
    41  sudo chmod +x ./clusterctl-foo
    42  ```
    43  
    44  and place it anywhere in your `PATH`:
    45  
    46  ```bash
    47  sudo mv ./clusterctl-foo /usr/local/bin
    48  ```
    49  
    50  You may now invoke your plugin as a `clusterctl` command:
    51  
    52  ```bash
    53  clusterctl foo
    54  ```
    55  
    56  ```
    57  I am a plugin named clusterctl-foo
    58  ```
    59  
    60  All args and flags are passed as-is to the executable:
    61  ```bash
    62  clusterctl foo version
    63  ```
    64  
    65  ```
    66  1.0.0
    67  ```
    68  
    69  All environment variables are also passed as-is to the executable:
    70  
    71  ```bash
    72  export EXAMPLE_ENV_VAR=example-value
    73  clusterctl foo example-env-var
    74  ```
    75  
    76  ```
    77  example-value
    78  ```
    79  
    80  ```bash
    81  EXAMPLE_ENV_VAR=another-example-value clusterctl foo example-env-var
    82  ```
    83  
    84  ```
    85  another-example-value
    86  ```
    87  
    88  Additionally, the first argument that is passed to a plugin will always be the full path to the location where it was invoked ($0 would equal /usr/local/bin/clusterctl-foo in the example above).
    89  
    90  ## Naming a plugin
    91  
    92  A plugin determines the command path it implements based on its filename. Each sub-command in the path is separated by a dash (-). For example, a plugin for the command `clusterctl foo bar baz` would have the filename `clusterctl-foo-bar-baz`.