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
}