apigeectl

You are currently viewing version 1.11 of the Apigee hybrid documentation.This version is end of life. You should upgrade to a newer version. For more information, seeSupported versions.

apigeectl is a command-line interface (CLI)for installing and managing Apigee hybrid in a Kubernetes cluster. Forinformation on downloading and installingapigeectl, seeDownload and install apigeectl.

Note: You must havekubectlinstalled and set up on your Kubernetes administration machine to use theapigeectl command.

Scopes for applyingapigeectl

By usingapigeectl flags you control which scopes the command applies configuration changes to. For an overview of scopes within the Apigee hybrid runtime see theRuntime service configuration overview.

ScopeComponentsapigeectl flag
StorageCassandra--datastore
In-memory storageRedis--redis
EnvironmentRuntime
Synchronizer
UDCA		--all-envs
--env
OrganizationApigee Connect Agent
MART
Watcher		--org
ReportingLogger
Metrics		--telemetry

apigeectl syntax

apigeectl [command] [flags]

Where:

  • command: Specifies the operation you want to perform. For a complete list of commands, seeapigeectl commands.

  • flags: Specifies command parameters. For a complete list of flags, seeapigeectl flags.

apigeectl commands

The following table lists theapigeectl commands:

CommandDescription
apply

Applies configurations for Apigee hybridruntime components to your Kubernetes cluster.

apigeectl apply without flags will apply changes to all components in the cluster.

apigeectl flags:--all-envs,--datastore,--dry-run,--env,-f,--file-override-config,--help,--org,--print-yaml,--redis,--settings virtualhosts,--telemetry,--v

Note: After a fresh install or an upgrade, you must callapigeectl init before callingapigeectl apply.
check-ready

Checks the status of the hybrid component pods. When all component pods are ready, the message "All containers ready" is output. For automated scripting, note that the command exits with a status of 0 when the containers are all ready. When there is at least one pod not ready, the command exits with a status of 1.

apigeectl flags:-f,--file-override-config,--help,--v

deleteWarning:

Using theapigeectl delete command with the--all flag (for example,apigeectl delete --all -f overrides.yaml) will also delete backup data for all CSI volume snapshots.

Deletes hybrid components from the cluster. Use the--all flag to remove ALL of the components. If you omit--all, only the Apigee-specific components are removed (the components installed withapigeectl init are not deleted). Apigee-specific components are the components that are installed with theapply command.

apigeectl delete without any optional flags applies thedelete command to all of the components deployed in the cluster.

apigeectl diagnostic delete -fOVERRIDES_FILE deletes theapigee-diagnostic namespace created byapigeectl diagnostic. The-f /--file-override-config flag is required withapigeectl diagnostic delete

apigeectl flags:--all,--all-envs,--datastore,--env,-f,--file-override-config,--help,--org,--redis,--telemetry,--v

For more information, seeUninstall hybrid runtime.
diagnostic

Invokes the Diagnostic collector, which captures diagnostic data on the Kubernetes components of an Apigee hybrid instance on demand and stores them in Google Cloud storage buckets.

Diagnostic collector requires a named Google Cloud storage bucket, a service account with theStorage Admin role, and adiagnostic: stanza added to youroverrides file. See:

When you invoke Diagnostic collector, it creates an "apigee-diagnostic" Kubernetes namespace. You must delete this withapigeectl diagnostic delete before invoking Diagnostic collector again.

Invoke Diagnostic collector:

apigeectl diagnostic -fOVERRIDES_FILE

Delete Diagnostic collector:

apigeectl diagnostic delete -fOVERRIDES_FILE

apigeectl flags:--file-override-config

encode

Returns a list of encoded names of all the ApigeeDeployments for the specified organization or the specified environment within the specified organization. The encoded names include the name of the component with a hashed name of the organization and if using the--env flag, a hashed name of the environment. Apigee hybrid creates hashed names of organizations and environments to be able to avoid namespace collisions.

You must use either the--orgorg-name or both the--orgorg-name with the--envenv-name flags withencode. For example:

./apigeectl encode --org hybrid-exampleList of ApigeeDeployments are:  apigee-connect-agent-hybrid-example-6a82f8a  apigee-mart-hybrid-example-6a82f8a  apigee-watcher-hybrid-example-6a82f8a
./apigeectl encode --org hybrid-example --env example-envList of ApigeeDeployments are:  apigee-runtime-hybrid-example-example-env-9e87e2d  apigee-synchronizer-hybrid-example-example-env-9e87e2d  apigee-udca-hybrid-example-example-env-9e87e2d

apigeectl flags:--env,--org

helpPrints online help.
init

Installs Apigee Operators and CRDs in the apigee-system namespace.

Runapigeectl init after a fresh install or upgrade before runningapigeectl apply.

apigeectl flags:-f,--file-override-config,--help,--v

versionPrints the CLI version information.

apigeectl flag:--help

apigeectl flags

The following table lists theapigeectl flags:

FlagDescription
--allWarning:

Using theapigeectl delete command with the--all flag (for example,apigeectl delete --all -f overrides.yaml) will also delete backup data for all CSI volume snapshots.

delete only: Deletes the entire Apigee hybrid installation except ASM (Istio) and cert-manager from your cluster.
--all-envs

Applies theapigeectl command to all environments under the organization specified in your overrides config file.

--datastore

Applies the configuration to the datastore scope (Cassandra).

--dry-runExecutes the specified command without changing the cluster. Use with--print-yaml to output the rendered object spec to a file.

--dry-run must be used with one of the two following values, depending on the version of kubectl you are running. Usegcloud version to check your kubectl version:

  • kubectl version 1.17.x or older:--dry-run=true
  • kubectl version 1.18.x or newer:--dry-run=client
--envenv-name

Applies the configuration to the specified environment. This flag will apply configuration to environment scope components apigee-runtime, apigee-synchronizer and apigee-udca.

--env must be used with the--org flag. For example:

apigeectl apply --org hybrid-example --env example-env \      -f overrides/overrides.yaml
-f
‑‑file-override-config		Specifies a YAML file containing custom configuration properties for the hybrid deployment. The default value is./overrides.yaml. An overrides file is required for theapply,check-ready,delete, andinit commands.

You must specify the full path with this flag. For more information, seeManaging runtime plane components.

-h
--help		Displays help for the command.
--org

Applies the configuration to the specified organization. This flag will apply configuration to the org scope components apigee-connect-agent, apigee-mart and apigee-watcher.

Note: When using--org withencode you must include the organization ID. For example:
apigeectl encode --org example-org
--print-yamlPrints the configuration template output to stdout. For an example that uses this flag, seePrint the configuration to a file.
--redis

Applies the configuration to the in-memory data storage scope (Redis).

--restore

Restores Cassandra to a previously saved snapshot specified by thesnapshotTimestamp property inrestore configuration of theoverrides.yaml file. The backup is restored either from the Cloud Storage bucket or a remote server based on thebackup configuration in theoverrides.yaml file. For more information, seeRestoring a region from a backup.

-s
--settingsvirtualhosts

Specifies a configuration to which the command applies. Currently, this flag is only supported for thevirtualhosts configuration, which is part of theruntime component. Use this flag if you make changes to thevirtualhosts property, and nothing else.

For example, if you make a change to thevirtualhosts configuration in your overrides file, apply it to the cluster with this command:

apigeectl apply -fmy-overrides.yaml --settings virtualhosts \    --org example-org --env example-env
--telemetry

Applies the configuration for telemetry components like apigee-logger and apigee-metrics.

--vint

Prints verbose logs to std err.int is an integer that sets the level of verbosity.int is required with--v. This option behaves identically to thekubectl--v option.

Note: This option replaces the deprecated--verbose option.

Theapigeectl command useskubectl behind the scenes to do its work. Theapigeectl command options (apply anddelete, and the use of YAML configuration files, are similar to their kubectl counterparts. To learn more about how objects are managed in a Kubernetes cluster, see the following topics:

Examples

Initialize the cluster configuration

Apply prerequisite component configurations to your cluster withinit. You must run theinit command beforeapply.

apigeectl init -f my_overrides.yaml

Apply the cluster configuration

To apply hybrid configurations to your Kubernetes cluster, use theapply command. The first time you runapply all of thehybrid runtime components are created in your cluster. If you make configuration changes, rerunapply to apply only the changes or use flags to apply changes to a specificscope only.

The following example applies the configuration for hybrid runtime plane components to your cluster:

apigeectl apply -f my_overrides.yaml

Apply the configuration for a single component

To restrict theapply command to a particular component, use the flags described inapigeectl flags.

The following example only applies the configuration for the Cassandra component:

apigeectl apply --datastore -f my_overrides.yaml

Print the configuration to a file

If you're debugging an installation problem, it's useful to print out the entire cluster configuration to a file so that you can inspect the configuration settings. The--print-yaml flag prints the hybrid configuration to stdout, and the--dry-run flag allows the command to run without making any changes to the cluster.

apigeectl apply -f my_overrides.yaml --dry-run=client --print-yaml > apigee-hybrid.yaml
Note: It is a good practice to save a copy ofthe YAML output in source control for future reference. But be aware that the output file containspasswords and secrets that you may not want to store.

Check pod status

The following example checks the status of pods deployed to your cluster:

apigeectl check-ready -f overrides/overrides.yamlAll containers ready in namespace 'my-namespace'

Delete hybrid from the cluster

For details, seeUninstall hybrid runtime.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-18 UTC.