Payara Cloud CLI User Guide
Introduction
pcl
is command line utility for managing Payara Cloud namespaces and applications.
It is distributed as executable jar file.
It requires Java Runtime, version 8 or newer.
Getting started
Command Line Client prerequisities
Command Line Client is distributed as a zip package containing the client, shell wrappers for Windows and Unix-like systems and documentation package just like this one.
The client itself is an executable .jar
file, that requires at least Java 8 to be available on the system.
Downloading the Commnand Line Client
Client is distributed over Payara’s Nexus Repository under following coordinates:
<dependency>
<groupId>fish.payara.cloud</groupId>
<artifactId>pcl</artifactId>
<version>1.1.0</version>
</dependency>
Maven Repository Settings
<repository> <releases><enabled>true</enabled></releases> <snapshots><enabled>false</enabled></snapshots> <id>payara-artifacts</id> <name>Payara Artifacts</name> <url>https://nexus.payara.fish/repository/payara-artifacts/</url> </repository>
Logging in
pcl
uses OAuth Device Authentication flow to establish its identity to Payara Cloud.
It will generate a confirmation code, which you use to log in to Payara Cloud web interface via browser.
pcl login [INFO] In order to log in follow following link: https://login.payara.cloud/activate [INFO] Your confirmation code is KKMD-STTF
The client will also open the browser for you if your environment permits it. In case you follow link manually you’ll need to enter the confirmation code on first page:
After that a confirmation page is displayed:
Only confirm this page if you knowingly initiated login flow via pcl login , payara-cloud-maven-plugin or Payara IDE plugins .
Payara Cloud will never ask you to authenticate via this flow via any other channel or under any other circumstance, such as solving a support issue.
|
If you are logging in for the first time the authentication service will ask you to authorize Payara Cloud CLI to perform application management tasks with your identity:
After confirming this, the authentication process is completed and you may close the browser window:
Managing tokens
After login is complete the relevant token is stored in $HOME/.payara/manage.payara.cloud
.
The token does not have any expiration time, so you will not need to log in again for when using pcl
.
Tokens can be invalidated remotely via User Preferences screen in Payara Cloud Web UI.
Non-interactive usage
Login only works for interactive sessions.
In order to be able to perform pcl
commands in non-interactive environments such as CI pcl login
offers option --print-token
.
pcl login --print-token [INFO] In order to log in follow following link: https://login.payara.cloud/activate [INFO] Your confirmation code is CVJF-XKGH [SUCCESS] Token for environment-based login: PCL_AUTH_TOKEN=eyJyZWZyZXNoX3Rva2VuIjoiWktMTFVQaUVIeEZ3c2JfOGNXSzFILUdnaUR1OVlXZUdDR3h3TUVFUlVrM3VLIn0=
The output of the command is the environment to use in order to establish the identity in a script.
In Github Actions the token can be used in following way:
Set secret PCL_AUTH_TOKEN
for the repository to eyJyZWZyZXNoX3Rva2VuIjoiWktMTFVQaUVIeEZ3c2JfOGNXSzFILUdnaUR1OVlXZUdDR3h3TUVFUlVrM3VLIn0=
.
In the workflow file refer to the secret like this:
- name: Deploy new version env: PCL_AUTH_TOKEN: ${{ secrets.PCL_AUTH_TOKEN }} run: pcl -n project-head -a main-app upload target/app.war --deploy
Common options
Obtaining help
Option --help
will provide with same content as Command Reference does, listing all available options and a short description of the command.
pcl --help Payara Cloud Command Line. Usage: pcl [-hqV] [-a=<applicationName>] [-n=<namespaceName>] [-o=<outputFormat>] [-s=<subscriptionName>] [COMMAND] Payara Cloud Command Line Interface allows remote operations over Payara Cloud's namespaces and application via command line. In order to sign in, use the command `pcl login` interactively. This will allow the client to obtain credentials that are either stored in home directory or can be provided via environment variable `PCL_AUTH_TOKEN`. See `pcl login --help` for details. -a, --application=<applicationName> Name of application to manage. Not required for commands listed by `-n` option, as well as `list-applications` and `upload`. -h, --help Show this help message and exit. -n, --namespace=<namespaceName> Name of namespace to manage. Required for all commands except `login`, `list-namespaces` and `create-namespace`. -o, --output=<outputFormat> Output format. Allowed values: TEXT, JSON. -q, --quiet Quiet output. Only result of operations will be displayed to `stdout`, or error message to `stderrr`. -s, --subscription=<subscriptionName> Name of subscription to use. Only necessary when account has access to multiple subscriptions. -V, --version Print version information and exit. Commands: login Log in to Payara Cloud instance. list-subscriptions Get list of subscriptions available to user. list-namespaces List namespaces available in a subscription. list-applications List applications present in a namespace. upload Upload application binary deploy Deploy an existing application. start Start an application stop Stop an application create-namespace Create new namespace delete-namespace Deletes a namespace. delete-application Delete an application. configure Change configuration of an application scale Scale an application
To find out about specific commands put --help
after the command:
pcl upload --help Usage: pcl upload [-ehqV] [--deploy] [-a=<applicationName>] [-n=<namespaceName>] [-o=<outputFormat>] [-s=<subscriptionName>] [-t=<timeout>] <file> Upload application binary Use to either provide new binary for existing application by specifying option `-a` / `--application`, or to upload new application into a namespace. <file> Application archive file (.war) to be uploaded -a, --application=<applicationName> Name of application to manage. Not required for commands listed by `-n` option, as well as `list-applications` and `upload`. --deploy Deploy application immediately. Application will be immediately deployed after upload if its default configuration is complete, i. e. all required option have default values. -e, --fail-early Fail command immediately after first deployment problem instead of waiting for timeout on client or backend side There are certain scenarios when deployment can succeed despite deployment problems reported. It is therefore not guaranteed that application deployment that failed with early warning will not start up later. -h, --help Show this help message and exit. -n, --namespace=<namespaceName> Name of namespace to manage. Required for all commands except `login`, `list-namespaces` and `create-namespace`. -o, --output=<outputFormat> Output format. Allowed values: TEXT, JSON. -q, --quiet Quiet output. Only result of operations will be displayed to `stdout`, or error message to `stderrr`. -s, --subscription=<subscriptionName> Name of subscription to use. Only necessary when account has access to multiple subscriptions. -t, --timeout=<timeout> Duration in seconds specifying how long to wait for deployment to complete This is client side timeout which doesn't affect deployment process in Payara Cloud. It is therefore not guaranteed that application deployment that failed due to this time out will not eventually start up later. -V, --version Print version information and exit.
Determining version
This prints helpful information to determine the version and environment the command runs in.
pcl -V pcl version: development-snapshot Java version: 11.0.13, Vendor: Eclipse Adoptium, Platform encoding: UTF-8 OS: Windows 10, Version: 10.0, Arch: amd64
Output options
Option -o json
can be used to force output to be JSON only, including error messages.
Even though many commands return json in current version, it is possible that default console output will change in future versions.
Output of -o json
is planned to remain stable.
Compare json output to those console outputs shown in Listing Namespaces and Creating a Namespace below:
pcl -o json list-namespaces [{"href":"https://manage.payara.cloud/application/4727ef01-7811-4e5d-be9e-0847017bfc87/n/cli:clitest:efacd05c/","rel":"https://api.payara.cloud/entity/namespace","name":"cli-clitest","liveURI":"https://cli-clitest-xxxxxxxx.payara.app/","title":"cli-clitest"},{"href":"https://manage.payara.cloud/application/4727ef01-7811-4e5d-be9e-0847017bfc87/n/start:dev:85cafb11/","rel":"https://api.payara.cloud/entity/namespace","name":"start-dev","liveURI":"https://start-dev-xxxxxxxx.payara.app/","title":"start-dev"}]
pcl -o json create-namespace --project cli --stage clitest {"timestamp":"2023-01-13T16:57:43.854254200Z","kind":"error","message":"Backend rejected the request: Namespace with this project / stage combination already exists (diagnostic id https://api.payara.cloud/error-instance/lcurj8l3)"}
Option -q
will suppress all progress and warning messages, puting just the output onto stdout
or error messages to stderr
.
Namespace Management
Basic namespace operations are available via CLI. Other use cases, such as set up of custom domains or monitoring are only available via GUI.
Listing Namespaces
Use list-namespaces to see namespaces available to you:
pcl list-namespaces [SUCCESS] Namespaces: cli-clitest name: cli-clitest liveURI: https://cli-clitest-xxxxxxxx.payara.app/ start-dev name: start-dev liveURI: https://start-dev-xxxxxxxx.payara.app/
For all other commands that operate on namespace, you must supply the value of name (e. g. start-dev
) as option -n
.
Creating a Namespace
Creating namespace with create-namespace takes exact same input as GUI — project and stage the namespace should represent:
pcl create-namespace --project cli --stage clitest [SUCCESS] Namespace was created { "name": "cli-clitest", "cluster": { "name": "Azure, West Europe" }, "liveURI": "https://cli-clitest-xxxxxxxx.payara.app/" }
Additionally, one can specify the provider and region namespace will be provisioned via option --region
:
Region value | Provider | Region |
---|---|---|
|
Azure |
West Europe (default) |
|
Azure |
East US |
pcl create-namespace --project cli --stage clitest --region azure-eastus [SUCCESS] Namespace was created { "name": "cli-clitest", "cluster": { "name": "Azure, East US" }, "liveURI": "https://cli-clitest-xxxxxxxx.payara.app/" }
Payara Cloud can extend to support more regions and providers. The value is therefore checked after submission. If an invalid value is provided valid values for region will be provided in a warning message:
pcl create-namespace --project cli --stage clitest --region unsupported [FAILURE] Backend rejected the request: Applicable values for region are: azure-westeurope (Azure, West Europe), azure-eastus (Azure, East US) (diagnostic id https://api.payara.cloud/error-instance/lcurjko0)
Project and stage need to be unique within your subscription. An error is reported when you attempt to create a namespace with same project/stage combination:
pcl create-namespace --project cli --stage clitest [FAILURE] Backend rejected the request: Namespace with this project / stage combination already exists (diagnostic id https://api.payara.cloud/error-instance/lcurj5vw)
Deleting a Namespace
Namespace can be deleted by using delete-namespace command:
pcl delete-namespace --namespace $namespace -y [SUCCESS] Namespace has been deleted
Deleting the namespace permanently removes all applications and their configurations.
Option -y
is required to confirm this step, otherwise a warning is displayed:
pcl delete-namespace -n $namespace [WARN] To confirm you are sure about deleting this namespace, pass option -y on the command line { "name": "cli-clitest", "cluster": { "name": "Azure, West Europe" }, "liveURI": "https://cli-clitest-xxxxxxxx.payara.app/" }
Application Management
CLI supports all usecases related to uploading a war file, configuring it and starting the revision.
Uploading .war File
A new application can be created within a namespace by uploading its binary artifact using the upload command:
pcl upload -n $namespace $warFile [UPDATE] State of inspection process is CREATED [SUCCESS] Application uploaded { "name": "game-demo", "pendingChanges": true, "status": "PENDING" }
Uploading an artifact starts an inspection process, which performs scanning of the .war file whilst identifying microprofile config properties, persistence units and datasources the application might require.
The application name is determined from Maven metadata in META-INF/maven
by default.
Should you want to override that, provide option -a
/--application
:
pcl upload -n $namespace -a $appName $warFile [UPDATE] State of inspection process is CREATED [SUCCESS] Application uploaded { "name": "pass-deploy", "pendingChanges": true, "status": "PENDING" }
Status PENDING
signifies that application has not been deployed yet.
Deployment can be either performed by the deploy command, or by providing option --deploy
to the upload
command.
pcl upload -n $namespace $warFile --deploy [UPDATE] State of inspection process is DEPLOYING [UPDATE] State of deployment process is DEPLOYING [UPDATE] State of deployment process is DEPLOYED [SUCCESS] Deployment completed { "name": "game-demo", "applicationEndpoint": "https://cli-clitest-xxxxxxxx.payara.app/", "pendingChanges": false, "status": "RUNNING", "liveRuntimeSize": "QUARTER_CORE" }
Here we see that inspection process is immediately followed by deployment process that starts up the application in target provisioning cluster.
Uploading a new .war
for an existing application doesn’t immediately deploy it.
The information that the newest state of the application is different from deployed state is represented by attribute pendingChanges
, which is true
in such case.
pcl upload -n $namespace -a $appName $warFile [UPDATE] State of inspection process is CREATED [SUCCESS] Application uploaded { "name": "game-demo", "applicationEndpoint": "https://cli-clitest-xxxxxxxx.payara.app/", "pendingChanges": true, "status": "RUNNING", "liveRuntimeSize": "QUARTER_CORE" }
Deploying Application
To deploy an application as a separate step (for example after configuring it) use the deploy command:
pcl deploy -n $namespace -a $appName [UPDATE] State of deployment process is DEPLOYING [UPDATE] State of deployment process is DEPLOYED [SUCCESS] Deployment completed { "name": "game-demo", "applicationEndpoint": "https://cli-clitest-xxxxxxxx.payara.app/", "pendingChanges": false, "status": "RUNNING", "liveRuntimeSize": "QUARTER_CORE" }
Payara Cloud will keep retrying deployment for up to 10 minutes before it pronounces deployment failed. There are two switches to enable CLI terminate before the 10 minutes, in the scenario of deployment failure.
Note that in either of these cases backend deployment is not cancelled. This is intentionally designed that way, because application deployment could be fail due to some external service not being available at startup.
First option is to set client-side timeout for deployment with --timeout
.
Exit code in such case is 3.
pcl -n $namespace -a $appName deploy --timeout 35 [UPDATE] State of deployment process is DEPLOYING [WARN] Exception while loading the app [WARN] Exception during lifecycle processing [WARN] org.glassfish.deployment.common.DeploymentException: CDI deployment failure:WELD-001408: Unsatisfied dependencies for type String with qualifiers @Default [WARN] at injection point [BackedAnnotatedField] @Inject cloud.payara.fail.injection.FailingServlet.notAvailable [WARN] at cloud.payara.fail.injection.FailingServlet.notAvailable(FailingServlet.java:0) [WARN] WELD-001475: The following beans match by type, but none have matching qualifiers: [WARN] - Producer Method [String] with qualifiers [@JaxRsParamQualifier @Any] declared as [[UnbackedAnnotatedMethod] @Produces @JaxRsParamQualifier public org.glassfish.jersey.ext.cdi1x.internal.CdiComponentProviderServerRuntimeSpecifics$JaxRsParamProducer.getParameterValue(InjectionPoint, BeanManager)], [WARN] - Producer Method [String] with qualifiers [@BatchProperty @Any] declared as [[UnbackedAnnotatedMethod] @Produces @Dependent @BatchProperty public com.ibm.jbatch.container.cdi.BatchProducerBean.produceProperty(InjectionPoint)] [WARN] -- WELD-001408: Unsatisfied dependencies for type String with qualifiers @Default [WARN] at injection point [BackedAnnotatedField] @Inject cloud.payara.fail.injection.FailingServlet.notAvailable [WARN] at cloud.payara.fail.injection.FailingServlet.notAvailable(FailingServlet.java:0) [WARN] WELD-001475: The following beans match by type, but none have matching qualifiers: [WARN] - Producer Method [String] with qualifiers [@JaxRsParamQualifier @Any] declared as [[UnbackedAnnotatedMethod] @Produces @JaxRsParamQualifier public org.glassfish.jersey.ext.cdi1x.internal.CdiComponentProviderServerRuntimeSpecifics$JaxRsParamProducer.getParameterValue(InjectionPoint, BeanManager)], [WARN] - Producer Method [String] with qualifiers [@BatchProperty @Any] declared as [[UnbackedAnnotatedMethod] @Produces @Dependent @BatchProperty public com.ibm.jbatch.container.cdi.BatchProducerBean.produceProperty(InjectionPoint)] [WARN] at org.jboss.weld.bootstrap.Validator.validateInjectionPointForDeploymentProblems(Validator.java:378) [WARN] at org.jboss.weld.bootstrap.Validator.validateInjectionPoint(Validator.java:290) [WARN] at org.jboss.weld.bootstrap.Validator.validateGeneralBean(Validator.java:143) [WARN] at org.jboss.weld.bootstrap.Validator.validateRIBean(Validator.java:164) [WARN] at org.jboss.weld.bootstrap.Validator.validateBean(Validator.java:526) [WARN] at org.jboss.weld.bootstrap.ConcurrentValidator$1.doWork(ConcurrentValidator.java:64) [WARN] at org.jboss.weld.bootstrap.ConcurrentValidator$1.doWork(ConcurrentValidator.java:62) [WARN] at org.jboss.weld.executor.IterativeWorkerTaskFactory$1.call(IterativeWorkerTaskFactory.java:62) [WARN] at org.jboss.weld.executor.IterativeWorkerTaskFactory$1.call(IterativeWorkerTaskFactory.java:55) [WARN] at org.glassfish.weld.services.ExecutorServicesImpl.lambda$inContextClassloader$0(ExecutorServicesImpl.java:123) [WARN] at org.glassfish.weld.services.ExecutorServicesImpl.lambda$inContextClassloader$0(ExecutorServicesImpl.java:123) [WARN] at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264) [WARN] at org.glassfish.enterprise.concurrent.internal.ManagedFutureTask.run(ManagedFutureTask.java:143) [WARN] at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128) [WARN] at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628) [WARN] at java.base/java.lang.Thread.run(Thread.java:829) [WARN] at org.glassfish.enterprise.concurrent.ManagedThreadFactoryImpl$ManagedThread.run(ManagedThreadFactoryImpl.java:250) [WARN] Exception while loading the app : CDI deployment failure:WELD-001408: Unsatisfied dependencies for type String with qualifiers [WARN] @Default [WARN] at injection point [BackedAnnotatedField] @Inject cloud.payara.fail.injection.FailingServlet.notAvailable [WARN] at cloud.payara.fail.injection.FailingServlet.notAvailable(FailingServlet.java:0) [WARN] WELD-001475: The following beans match by type, but none have matching qualifiers: [WARN] - Producer Method [String] with qualifiers [@JaxRsParamQualifier @Any] declared as [[UnbackedAnnotatedMethod] @Produces @JaxRsParamQualifier public org.glassfish.jersey.ext.cdi1x.internal.CdiComponentProviderServerRuntimeSpecifics$JaxRsParamProducer.getParameterValue(InjectionPoint, BeanManager)], [WARN] - Producer Method [String] with qualifiers [@BatchProperty @Any] declared as [[UnbackedAnnotatedMethod] @Produces @Dependent @BatchProperty public com.ibm.jbatch.container.cdi.BatchProducerBean.produceProperty(InjectionPoint)] [WARN] -- WELD-001408: Unsatisfied dependencies for type String with qualifiers @Default [WARN] at injection point [BackedAnnotatedField] @Inject cloud.payara.fail.injection.FailingServlet.notAvailable [WARN] at cloud.payara.fail.injection.FailingServlet.notAvailable(FailingServlet.java:0) [WARN] WELD-001475: The following beans match by type, but none have matching qualifiers: [WARN] - Producer Method [String] with qualifiers [@JaxRsParamQualifier @Any] declared as [[UnbackedAnnotatedMethod] @Produces @JaxRsParamQualifier public org.glassfish.jersey.ext.cdi1x.internal.CdiComponentProviderServerRuntimeSpecifics$JaxRsParamProducer.getParameterValue(InjectionPoint, BeanManager)], [WARN] - Producer Method [String] with qualifiers [@BatchProperty @Any] declared as [[UnbackedAnnotatedMethod] @Produces @Dependent @BatchProperty public com.ibm.jbatch.container.cdi.BatchProducerBean.produceProperty(InjectionPoint)] [FAILURE] Timed out waiting for deployment to finish
Another option is to fail immediately after deployment problem is identified by using the option --fail-early
.
Exit code in such case is 2.
pcl -n $namespace -a $appName deploy --fail-early [UPDATE] State of deployment process is DEPLOYING [WARN] Exception while loading the app [WARN] Exception during lifecycle processing [WARN] org.glassfish.deployment.common.DeploymentException: CDI deployment failure:WELD-001408: Unsatisfied dependencies for type String with qualifiers @Default [WARN] at injection point [BackedAnnotatedField] @Inject cloud.payara.fail.injection.FailingServlet.notAvailable [WARN] at cloud.payara.fail.injection.FailingServlet.notAvailable(FailingServlet.java:0) [WARN] WELD-001475: The following beans match by type, but none have matching qualifiers: [WARN] - Producer Method [String] with qualifiers [@BatchProperty @Any] declared as [[UnbackedAnnotatedMethod] @Produces @Dependent @BatchProperty public com.ibm.jbatch.container.cdi.BatchProducerBean.produceProperty(InjectionPoint)], [WARN] - Producer Method [String] with qualifiers [@JaxRsParamQualifier @Any] declared as [[UnbackedAnnotatedMethod] @Produces @JaxRsParamQualifier public org.glassfish.jersey.ext.cdi1x.internal.CdiComponentProviderServerRuntimeSpecifics$JaxRsParamProducer.getParameterValue(InjectionPoint, BeanManager)] [WARN] -- WELD-001408: Unsatisfied dependencies for type String with qualifiers @Default [WARN] at injection point [BackedAnnotatedField] @Inject cloud.payara.fail.injection.FailingServlet.notAvailable [WARN] at cloud.payara.fail.injection.FailingServlet.notAvailable(FailingServlet.java:0) [WARN] WELD-001475: The following beans match by type, but none have matching qualifiers: [WARN] - Producer Method [String] with qualifiers [@BatchProperty @Any] declared as [[UnbackedAnnotatedMethod] @Produces @Dependent @BatchProperty public com.ibm.jbatch.container.cdi.BatchProducerBean.produceProperty(InjectionPoint)], [WARN] - Producer Method [String] with qualifiers [@JaxRsParamQualifier @Any] declared as [[UnbackedAnnotatedMethod] @Produces @JaxRsParamQualifier public org.glassfish.jersey.ext.cdi1x.internal.CdiComponentProviderServerRuntimeSpecifics$JaxRsParamProducer.getParameterValue(InjectionPoint, BeanManager)] [WARN] at org.jboss.weld.bootstrap.Validator.validateInjectionPointForDeploymentProblems(Validator.java:378) [WARN] at org.jboss.weld.bootstrap.Validator.validateInjectionPoint(Validator.java:290) [WARN] at org.jboss.weld.bootstrap.Validator.validateGeneralBean(Validator.java:143) [WARN] at org.jboss.weld.bootstrap.Validator.validateRIBean(Validator.java:164) [WARN] at org.jboss.weld.bootstrap.Validator.validateBean(Validator.java:526) [WARN] at org.jboss.weld.bootstrap.ConcurrentValidator$1.doWork(ConcurrentValidator.java:64) [WARN] at org.jboss.weld.bootstrap.ConcurrentValidator$1.doWork(ConcurrentValidator.java:62) [WARN] at org.jboss.weld.executor.IterativeWorkerTaskFactory$1.call(IterativeWorkerTaskFactory.java:62) [WARN] at org.jboss.weld.executor.IterativeWorkerTaskFactory$1.call(IterativeWorkerTaskFactory.java:55) [WARN] at org.glassfish.weld.services.ExecutorServicesImpl.lambda$inContextClassloader$0(ExecutorServicesImpl.java:123) [WARN] at org.glassfish.weld.services.ExecutorServicesImpl.lambda$inContextClassloader$0(ExecutorServicesImpl.java:123) [WARN] at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264) [WARN] at org.glassfish.enterprise.concurrent.internal.ManagedFutureTask.run(ManagedFutureTask.java:143) [WARN] at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128) [WARN] at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628) [WARN] at java.base/java.lang.Thread.run(Thread.java:829) [WARN] at org.glassfish.enterprise.concurrent.ManagedThreadFactoryImpl$ManagedThread.run(ManagedThreadFactoryImpl.java:250) [WARN] Exception while loading the app : CDI deployment failure:WELD-001408: Unsatisfied dependencies for type String with qualifiers [WARN] @Default [WARN] at injection point [BackedAnnotatedField] @Inject cloud.payara.fail.injection.FailingServlet.notAvailable [WARN] at cloud.payara.fail.injection.FailingServlet.notAvailable(FailingServlet.java:0) [WARN] WELD-001475: The following beans match by type, but none have matching qualifiers: [WARN] - Producer Method [String] with qualifiers [@BatchProperty @Any] declared as [[UnbackedAnnotatedMethod] @Produces @Dependent @BatchProperty public com.ibm.jbatch.container.cdi.BatchProducerBean.produceProperty(InjectionPoint)], [WARN] - Producer Method [String] with qualifiers [@JaxRsParamQualifier @Any] declared as [[UnbackedAnnotatedMethod] @Produces @JaxRsParamQualifier public org.glassfish.jersey.ext.cdi1x.internal.CdiComponentProviderServerRuntimeSpecifics$JaxRsParamProducer.getParameterValue(InjectionPoint, BeanManager)] [WARN] -- WELD-001408: Unsatisfied dependencies for type String with qualifiers @Default [WARN] at injection point [BackedAnnotatedField] @Inject cloud.payara.fail.injection.FailingServlet.notAvailable [WARN] at cloud.payara.fail.injection.FailingServlet.notAvailable(FailingServlet.java:0) [WARN] WELD-001475: The following beans match by type, but none have matching qualifiers: [WARN] - Producer Method [String] with qualifiers [@BatchProperty @Any] declared as [[UnbackedAnnotatedMethod] @Produces @Dependent @BatchProperty public com.ibm.jbatch.container.cdi.BatchProducerBean.produceProperty(InjectionPoint)], [WARN] - Producer Method [String] with qualifiers [@JaxRsParamQualifier @Any] declared as [[UnbackedAnnotatedMethod] @Produces @JaxRsParamQualifier public org.glassfish.jersey.ext.cdi1x.internal.CdiComponentProviderServerRuntimeSpecifics$JaxRsParamProducer.getParameterValue(InjectionPoint, BeanManager)] [FAILURE] Failing early due to reported deployment problem
Listing Applications
In order to list applications within a namespace use command list-applications, that shows application names and their basic properties:
pcl list-applications -n $namespace [SUCCESS] Applications: game-demo name: game-demo applicationEndpoint: https://cli-clitest-xxxxxxxx.payara.app/ status: RUNNING other-app name: other-app applicationEndpoint: https://cli-clitest-xxxxxxxx.payara.app/other/ status: RUNNING
Stopping an Application
A running application can be stopped with stop, providing the application name.
pcl stop -n $namespace -a $appName [UPDATE] State of deployment process is DEPLOYING [UPDATE] State of deployment process is STOPPED [SUCCESS] Deployment completed { "name": "game-demo", "applicationEndpoint": "https://cli-clitest-xxxxxxxx.payara.app/", "pendingChanges": false, "status": "STOPPED", "liveRuntimeSize": "QUARTER_CORE" }
A warning is displayed when application is in a state that doesn’t permit stopping it:
pcl stop -n $namespace -a $appName [FAILURE] Application cannot be stopped
Starting an Application
A stopped application can be started again by using the start command.
pcl start -n $namespace -a $appName [UPDATE] State of deployment process is DEPLOYING [UPDATE] State of deployment process is DEPLOYED [SUCCESS] Deployment completed { "name": "game-demo", "applicationEndpoint": "https://cli-clitest-xxxxxxxx.payara.app/", "pendingChanges": false, "status": "RUNNING", "liveRuntimeSize": "QUARTER_CORE" }
If the application is not stopped, the command fails.
pcl start -n $namespace -a $appName [FAILURE] Application cannot be started
Configuring an Application
The most dynamic command of cli is configure.
Available sub-commands of configure
depend on specific application and the configuration options it provides.
The configuration of an application consists of several partial configurations, that describe particular facets of that application.
Semantics of partial configuration is represented by configuration kind, such as data source or context root configuration).
Usually application has at most one partial configuration for each configuration kind, with only exception being data source, which has one configuration of kind dataSource
for every data source identified.
Available configuration kinds can be seen by invoking detailed help of configure
command while also specifying the target application:
pcl -n $namespace -a $appName configure --help Usage: configure [-ehV] [--deploy] [-t=<timeout>] [<CONFIGURATION KIND> key=value...]... --deploy Deploy revision with updated configuration immediately -e, --fail-early Fail command immediately after first deployment problem instead of waiting for timeout on client or backend side There are certain scenarios when deployment can succeed despite deployment problems reported. It is therefore not guaranteed that application deployment that failed with early warning will not start up later. -h, --help Show this help message and exit. -t, --timeout=<timeout> Duration in seconds specifying how long to wait for deployment to complete This is client side timeout which doesn't affect deployment process in Payara Cloud. It is therefore not guaranteed that application deployment that failed due to this time out will not eventually start up later. -V, --version Print version information and exit. Configuration kinds: microprofileConfig appRuntime contextRoot
pcl -n $namespace -a $appName configure contextRoot --help Usage: configure contextRoot [-ehV] [--deploy] [-t=<timeout>] [--add=<key>=<value>]... [--reset=<removedParameters>]... [<key>=<value>...] [<key>=<value>...] Property to set in a configuration --add=<key>=<value> Properties to add to configuration --deploy Deploy revision with updated configuration immediately -e, --fail-early Fail command immediately after first deployment problem instead of waiting for timeout on client or backend side There are certain scenarios when deployment can succeed despite deployment problems reported. It is therefore not guaranteed that application deployment that failed with early warning will not start up later. -h, --help Show this help message and exit. --reset=<removedParameters> Properties to reset to default value or remove -t, --timeout=<timeout> Duration in seconds specifying how long to wait for deployment to complete This is client side timeout which doesn't affect deployment process in Payara Cloud. It is therefore not guaranteed that application deployment that failed due to this time out will not eventually start up later. -V, --version Print version information and exit. Recognized configuration parameters: exposedPaths appName contextRoot
Recognized configuration parameters are keys that are known to exist for that particular configuration kind, and are reconfigured using syntax <parameter>=<value>
after specifyig the configuration kind.
When reconfiguration succeeds full configuration of the application as well as metadata about the keys is returned as result
pcl -n $namespace -a $appName configure contextRoot contextRoot=/game [SUCCESS] Revision reconfigured { "kind": { "microprofileConfig": { "pass-deploy.war": { "values": { "mp.jwt.verify.issuer": "fish.payara.demo", "quiz.lockout": "1500", "mp.jwt.verify.publickey.location": "publickey.pem", "maths.duration": "20", "quiz.duration": "20" }, "complete": true, "keys": [ { "name": "quiz.lockout", "required": false, "default": "1500" }, { "name": "mp.jwt.verify.issuer", "required": false, "default": "fish.payara.demo" }, { "name": "mp.jwt.verify.publickey.location", "required": false, "default": "publickey.pem" }, { "name": "maths.duration", "required": false, "default": "20" }, { "name": "quiz.duration", "required": false, "default": "20" } ] } }, "appRuntime": { "pass-deploy.war": { "values": { "runtimeSize": "QUARTER_CORE", "scalabilityType": "ROLLING_UPGRADE" }, "complete": true, "keys": [ { "name": "runtimeSize", "required": false }, { "name": "scalabilityType", "required": false } ] } }, "contextRoot": { "pass-deploy.war": { "values": { "exposedPaths": "/*", "appName": "game-demo", "contextRoot": "/game" }, "complete": true, "keys": [ { "name": "exposedPaths", "required": false }, { "name": "contextRoot", "required": true, "default": "/" }, { "name": "appName", "required": true, "default": "game-demo" } ] } } } }
Changes are not immediately deployed.
Command deploy needs to be invoked to make them live.
Alternatively option --deploy
can be passed to configure
to trigger deployment immediately after reconfiguring.
In such case output of the configure
command matches output of deploy
command.
pcl -n $namespace -a $appName configure microprofileConfig quiz.lockout=10 --deploy [WARN] Revision reconfigured [UPDATE] State of deployment process is DEPLOYING [UPDATE] State of deployment process is DEPLOYED [SUCCESS] Deployment completed { "name": "config-with-deploy", "applicationEndpoint": "https://cli-clitest-xxxxxxxx.payara.app/", "pendingChanges": false, "status": "RUNNING", "liveRuntimeSize": "QUARTER_CORE" }
If provided parameter does not meet the syntax requirements or the entire configuration is not consistent the commands ends with a failure.
pcl -n $namespace -a $appName configure contextRoot contextRoot=game [FAILURE] Backend rejected the request: 1 configurations are invalid in contextRoot --id=pass-deploy.war: contextRoot: Value must start with a slash
Client will prevent to define configuration keys, that are not known.
pcl -n $namespace -a $appName configure contextRoot ctxRoot=game [FAILURE] ctxRoot is not a valid option. If you want to add new property use --add ctxRoot=game
But it is valid use case to add a new property for microprofileConfig
, in which case option --add
needs to be used.
pcl -n $namespace -a $appName configure microprofileConfig --add new.app.config.property=value quiz.lockout=15 [SUCCESS] Revision reconfigured { "kind": { "microprofileConfig": { "pass-deploy.war": { "values": { "new.app.config.property": "value", "mp.jwt.verify.issuer": "fish.payara.demo", "quiz.lockout": "15", "mp.jwt.verify.publickey.location": "publickey.pem", "maths.duration": "20", "quiz.duration": "20" }, "complete": true, "keys": [ { "name": "quiz.lockout", "required": false, "default": "1500" }, { "name": "new.app.config.property", "required": false }, { "name": "mp.jwt.verify.issuer", "required": false, "default": "fish.payara.demo" }, { "name": "mp.jwt.verify.publickey.location", "required": false, "default": "publickey.pem" }, { "name": "maths.duration", "required": false, "default": "20" }, { "name": "quiz.duration", "required": false, "default": "20" } ] } }, "appRuntime": { "pass-deploy.war": { "values": { "runtimeSize": "QUARTER_CORE", "scalabilityType": "ROLLING_UPGRADE" }, "complete": true, "keys": [ { "name": "runtimeSize", "required": false }, { "name": "scalabilityType", "required": false } ] } }, "contextRoot": { "pass-deploy.war": { "values": { "appName": "game-demo", "contextRoot": "/" }, "complete": true, "keys": [ { "name": "exposedPaths", "required": false }, { "name": "contextRoot", "required": true, "default": "/" }, { "name": "appName", "required": true, "default": "game-demo" } ] } } } }
Multiple configurations and their attributes can be set at same time:
pcl -n $namespace -a $appName configure contextRoot contextRoot=/cr exposedPaths=/ui/* microprofileConfig quiz.lockout=12 [SUCCESS] Revision reconfigured { "kind": { "microprofileConfig": { "pass-deploy.war": { "values": { "mp.jwt.verify.issuer": "fish.payara.demo", "quiz.lockout": "12", "mp.jwt.verify.publickey.location": "publickey.pem", "maths.duration": "20", "quiz.duration": "20" }, "complete": true, "keys": [ { "name": "quiz.lockout", "required": false, "default": "1500" }, { "name": "mp.jwt.verify.issuer", "required": false, "default": "fish.payara.demo" }, { "name": "mp.jwt.verify.publickey.location", "required": false, "default": "publickey.pem" }, { "name": "maths.duration", "required": false, "default": "20" }, { "name": "quiz.duration", "required": false, "default": "20" } ] } }, "appRuntime": { "pass-deploy.war": { "values": { "runtimeSize": "QUARTER_CORE", "scalabilityType": "ROLLING_UPGRADE" }, "complete": true, "keys": [ { "name": "runtimeSize", "required": false }, { "name": "scalabilityType", "required": false } ] } }, "contextRoot": { "pass-deploy.war": { "values": { "exposedPaths": "/ui/*", "appName": "game-demo", "contextRoot": "/cr" }, "complete": true, "keys": [ { "name": "exposedPaths", "required": false }, { "name": "contextRoot", "required": true, "default": "/" }, { "name": "appName", "required": true, "default": "game-demo" } ] } } } }
A configuration key can be reset to its default value, or removed if it doesn’t have default value and is not required.
This can be achieved with option --reset <key>
.
pcl -n $namespace -a $appName configure contextRoot --reset exposedPaths [SUCCESS] Revision reconfigured { "kind": { "microprofileConfig": { "pass-deploy.war": { "values": { "mp.jwt.verify.issuer": "fish.payara.demo", "quiz.lockout": "12", "mp.jwt.verify.publickey.location": "publickey.pem", "maths.duration": "20", "quiz.duration": "20" }, "complete": true, "keys": [ { "name": "quiz.lockout", "required": false, "default": "1500" }, { "name": "mp.jwt.verify.issuer", "required": false, "default": "fish.payara.demo" }, { "name": "mp.jwt.verify.publickey.location", "required": false, "default": "publickey.pem" }, { "name": "maths.duration", "required": false, "default": "20" }, { "name": "quiz.duration", "required": false, "default": "20" } ] } }, "appRuntime": { "pass-deploy.war": { "values": { "runtimeSize": "QUARTER_CORE", "scalabilityType": "ROLLING_UPGRADE" }, "complete": true, "keys": [ { "name": "runtimeSize", "required": false }, { "name": "scalabilityType", "required": false } ] } }, "contextRoot": { "pass-deploy.war": { "values": { "appName": "game-demo", "contextRoot": "/cr" }, "complete": true, "keys": [ { "name": "exposedPaths", "required": false }, { "name": "contextRoot", "required": true, "default": "/" }, { "name": "appName", "required": true, "default": "game-demo" } ] } } } }
To enable horizontal scaling, add a new property for appRuntime
to your configuration. Set the value of the scalabilityType
parameter to HORIZONTAL_SCALING
and specify the desired number of replicas.
pcl -n $namespace -a $appName configure appRuntime scalabilityType=HORIZONTAL_SCALING --add numberOfReplicas=4 [SUCCESS] Revision reconfigured { "kind": { "appRuntime": { "petclinic.war": { "values": { "numberOfReplicas": "4", "runtimeSize": "QUARTER_CORE", "runtimeType": "PAYARA6_JDK11", "dataGridMode": "ENABLED", "scalabilityType": "HORIZONTAL_SCALING" }, "complete": true, "keys": [ { "name": "dataGridMode", "required": false }, { "name": "numberOfReplicas", "required": false }, { "name": "runtimeSize", "required": false }, { "name": "runtimeType", "required": false }, { "name": "scalabilityType", "required": false } ] } }, "contextRoot": { "petclinic.war": { "values": { "exposedPaths": "/*", "appName": "petclinic-jakartaee", "contextRoot": "/game" }, "complete": true, "keys": [ { "name": "exposedPaths", "required": false }, { "name": "contextRoot", "required": true, "default": "/petclinic-jakartaee" }, { "name": "appName", "required": true, "default": "petclinic-jakartaee" } ] } }, "dataSource": { "java:comp/DefaultDataSource": { "values": { "datasourceClass": "org.h2.jdbcx.JdbcDataSource", "steadyPoolSize": "1", "maxWaitTime": "30000", "jdbcUrl": "<default>", "maxPoolSize": "10", "resourceType": "javax.sql.DataSource", "poolName": "java_comp_DefaultDataSource" }, "complete": true, "keys": [ { "name": "steadyPoolSize", "required": true, "default": "1" }, { "name": "maxPoolSize", "required": true, "default": "10" }, { "name": "maxWaitTime", "required": true, "default": "30000" }, { "name": "jdbcUrl", "required": true, "default": "<default>" }, { "name": "datasourceClass", "required": true, "default": "org.h2.jdbcx.JdbcDataSource" }, { "name": "resourceType", "required": true, "default": "javax.sql.DataSource" }, { "name": "user", "required": false }, { "name": "password", "required": false }, { "name": "poolName", "required": true, "default": "java_comp_DefaultDataSource" } ] } } } }
Logs can be seen in console with deployment progress.
pcl deploy -n $namespace -a $appName [UPDATE] State of deployment process is DEPLOYING [0/2] [UPDATE] State of deployment process is DEPLOYING [1/3] [UPDATE] State of deployment process is DEPLOYING [2/4] [UPDATE] State of deployment process is DEPLOYED [4/4] [SUCCESS] Deployment completed { "name": "petclinic-jakartaee", "applicationEndpoint": "https://start.zeromagic.io/game/", "pendingChanges": false, "status": "RUNNING", "horizontalScaling": true, "numberOfReplicas": 4, "liveRuntimeSize": "QUARTER_CORE" }
If the application is configured for horizontal scaling, you can scale it directly by specifying the desired number of instances.
pcl -n $namespace -a $appName scale --instances=4 [UPDATE] State of deployment process is DEPLOYING [UPDATE] State of deployment process is DEPLOYED [SUCCESS] Deployment completed { "name": "game-demo", "applicationEndpoint": "https://cli-clitest-xxxxxxxx.payara.app/", "pendingChanges": false, "status": "RUNNING", "numberOfReplicas": 4, "liveRuntimeSize": "QUARTER_CORE", "horizontalScaling": true }