github.com/iqoqo/nomad@v0.11.3-0.20200911112621-d7021c74d101/website/pages/docs/drivers/java.mdx (about)

     1  ---
     2  layout: docs
     3  page_title: 'Drivers: Java'
     4  sidebar_title: Java
     5  description: The Java task driver is used to run Jars using the JVM.
     6  ---
     7  
     8  # Java Driver
     9  
    10  Name: `java`
    11  
    12  The `java` driver is used to execute Java applications packaged into a Java Jar
    13  file. The driver requires the Jar file to be accessible from the Nomad
    14  client via the [`artifact` downloader](/docs/job-specification/artifact).
    15  
    16  ## Task Configuration
    17  
    18  ```hcl
    19  task "webservice" {
    20    driver = "java"
    21  
    22    config {
    23      jar_path    = "local/example.jar"
    24      jvm_options = ["-Xmx2048m", "-Xms256m"]
    25    }
    26  }
    27  ```
    28  
    29  The `java` driver supports the following configuration in the job spec:
    30  
    31  - `class` - (Optional) The name of the class to run. If `jar_path` is specified
    32    and the manifest specifies a main class, this is optional. If shipping classes
    33    rather than a Jar, please specify the class to run and the `class_path`.
    34  
    35  - `class_path` - (Optional) The `class_path` specifies the class path used by
    36    Java to lookup classes and Jars.
    37  
    38  - `jar_path` - (Optional) The path to the downloaded Jar. In most cases this will just be
    39    the name of the Jar. However, if the supplied artifact is an archive that
    40    contains the Jar in a subfolder, the path will need to be the relative path
    41    (`subdir/from_archive/my.jar`).
    42  
    43  - `args` - (Optional) A list of arguments to the Jar's main method. References
    44    to environment variables or any [interpretable Nomad
    45    variables](/docs/runtime/interpolation) will be interpreted before
    46    launching the task.
    47  
    48  - `jvm_options` - (Optional) A list of JVM options to be passed while invoking
    49    java. These options are passed without being validated in any way by Nomad.
    50  
    51  ## Examples
    52  
    53  A simple config block to run a Java Jar:
    54  
    55  ```hcl
    56  task "web" {
    57    driver = "java"
    58  
    59    config {
    60      jar_path    = "local/hello.jar"
    61      jvm_options = ["-Xmx2048m", "-Xms256m"]
    62    }
    63  
    64    # Specifying an artifact is required with the "java" driver. This is the
    65    # mechanism to ship the Jar to be run.
    66    artifact {
    67      source = "https://internal.file.server/hello.jar"
    68  
    69      options {
    70        checksum = "md5:123445555555555"
    71      }
    72    }
    73  }
    74  ```
    75  
    76  A simple config block to run a Java class:
    77  
    78  ```hcl
    79  task "web" {
    80    driver = "java"
    81  
    82    config {
    83      class       = "Hello"
    84      class_path  = "${NOMAD_TASK_DIR}"
    85      jvm_options = ["-Xmx2048m", "-Xms256m"]
    86    }
    87  
    88    # Specifying an artifact is required with the "java" driver. This is the
    89    # mechanism to ship the Jar to be run.
    90    artifact {
    91      source = "https://internal.file.server/Hello.class"
    92  
    93      options {
    94        checksum = "md5:123445555555555"
    95      }
    96    }
    97  }
    98  ```
    99  
   100  ## Client Requirements
   101  
   102  The `java` driver requires Java to be installed and in your system's `$PATH`. On
   103  Linux, Nomad must run as root since it will use `chroot` and `cgroups` which
   104  require root privileges. The task must also specify at least one artifact to
   105  download, as this is the only way to retrieve the Jar being run.
   106  
   107  ## Client Attributes
   108  
   109  The `java` driver will set the following client attributes:
   110  
   111  - `driver.java` - Set to `1` if Java is found on the host node. Nomad determines
   112    this by executing `java -version` on the host and parsing the output
   113  - `driver.java.version` - Version of Java, ex: `1.6.0_65`
   114  - `driver.java.runtime` - Runtime version, ex: `Java(TM) SE Runtime Environment (build 1.6.0_65-b14-466.1-11M4716)`
   115  - `driver.java.vm` - Virtual Machine information, ex: `Java HotSpot(TM) 64-Bit Server VM (build 20.65-b04-466.1, mixed mode)`
   116  
   117  Here is an example of using these properties in a job file:
   118  
   119  ```hcl
   120  job "docs" {
   121    # Only run this job where the JVM is higher than version 1.6.0.
   122    constraint {
   123      attribute = "${driver.java.version}"
   124      operator  = ">"
   125      value     = "1.6.0"
   126    }
   127  }
   128  ```
   129  
   130  ## Resource Isolation
   131  
   132  The resource isolation provided varies by the operating system of
   133  the client and the configuration.
   134  
   135  On Linux, Nomad will attempt to use cgroups, namespaces, and chroot
   136  to isolate the resources of a process. If the Nomad agent is not
   137  running as root, many of these mechanisms cannot be used.
   138  
   139  As a baseline, the Java jars will be run inside a Java Virtual Machine,
   140  providing a minimum amount of isolation.