YARN-8881. [YARN-8851] Add basic pluggable device plugin framework. (…

…Zhankun Tang via wangda)

Change-Id: If9a2f68cd4713b4ec932cdeda68106f17437c3d3

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/api/deviceplugin/Device.java

@@ -0,0 +1,233 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hadoop.yarn.server.nodemanager.api.deviceplugin;
+
+import java.io.Serializable;
+import java.util.Objects;
+
+/**
+ * Represent one "device" resource.
+ * */
+public final class Device implements Serializable, Comparable {
+
+  private static final long serialVersionUID = -7270474563684671656L;
+
+  /**
+   * An plugin specified index number.
+   * Must set. Recommend starting from 0
+   * */
+  private final int id;
+
+  /**
+   * The device node like "/dev/devname".
+   * Optional
+   * */
+  private final String devPath;
+
+  /**
+   * The major device number.
+   * Optional
+   * */
+  private final int majorNumber;
+
+  /**
+   * The minor device number.
+   * Optional
+   * */
+  private final int minorNumber;
+
+  /**
+   * PCI Bus ID in format [[[[<domain>]:]<bus>]:][<slot>][.[<func>]].
+   * Optional. Can get from "lspci -D" in Linux
+   * */
+  private final String busID;
+
+  /**
+   * Is healthy or not.
+   * false by default
+   * */
+  private boolean isHealthy;
+
+  /**
+   * Plugin customized status info.
+   * Optional
+   * */
+  private String status;
+
+  /**
+   * Private constructor.
+   * @param builder
+   */
+  private Device(Builder builder) {
+    if (builder.id == -1) {
+      throw new IllegalArgumentException("Please set the id for Device");
+    }
+    this.id = builder.id;
+    this.devPath = builder.devPath;
+    this.majorNumber = builder.majorNumber;
+    this.minorNumber = builder.minorNumber;
+    this.busID = builder.busID;
+    this.isHealthy = builder.isHealthy;
+    this.status = builder.status;
+  }
+
+  public int getId() {
+    return id;
+  }
+
+  public String getDevPath() {
+    return devPath;
+  }
+
+  public int getMajorNumber() {
+    return majorNumber;
+  }
+
+  public int getMinorNumber() {
+    return minorNumber;
+  }
+
+  public String getBusID() {
+    return busID;
+  }
+
+  public boolean isHealthy() {
+    return isHealthy;
+  }
+
+  public String getStatus() {
+    return status;
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) {
+      return true;
+    }
+    if (o == null || getClass() != o.getClass()) {
+      return false;
+    }
+    Device device = (Device) o;
+    return id == device.getId()
+        && Objects.equals(devPath, device.getDevPath())
+        && majorNumber == device.getMajorNumber()
+        && minorNumber == device.getMinorNumber()
+        && Objects.equals(busID, device.getBusID());
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(id, devPath, majorNumber, minorNumber, busID);
+  }
+
+  @Override
+  public int compareTo(Object o) {
+    if (o == null || (!(o instanceof Device))) {
+      return -1;
+    }
+
+    Device other = (Device) o;
+
+    int result = Integer.compare(id, other.getId());
+    if (0 != result) {
+      return result;
+    }
+
+    result = Integer.compare(majorNumber, other.getMajorNumber());
+    if (0 != result) {
+      return result;
+    }
+
+    result = Integer.compare(minorNumber, other.getMinorNumber());
+    if (0 != result) {
+      return result;
+    }
+
+    result = devPath.compareTo(other.getDevPath());
+    if (0 != result) {
+      return result;
+    }
+
+    return busID.compareTo(other.getBusID());
+  }
+
+  @Override
+  public String toString() {
+    return "(" + getId() + ", " + getDevPath() + ", "
+        + getMajorNumber() + ":" + getMinorNumber() + ")";
+  }
+
+  /**
+   * Builder for Device.
+   * */
+  public final static class Builder {
+    // default -1 representing the value is not set
+    private int id = -1;
+    private String devPath = "";
+    private int majorNumber;
+    private int minorNumber;
+    private String busID = "";
+    private boolean isHealthy;
+    private String status = "";
+
+    public static Builder newInstance() {
+      return new Builder();
+    }
+
+    public Device build() {
+      return new Device(this);
+    }
+
+    public Builder setId(int i) {
+      this.id = i;
+      return this;
+    }
+
+    public Builder setDevPath(String dp) {
+      this.devPath = dp;
+      return this;
+    }
+
+    public Builder setMajorNumber(int maN) {
+      this.majorNumber = maN;
+      return this;
+    }
+
+    public Builder setMinorNumber(int miN) {
+      this.minorNumber = miN;
+      return this;
+    }
+
+    public Builder setBusID(String bI) {
+      this.busID = bI;
+      return this;
+    }
+
+    public Builder setHealthy(boolean healthy) {
+      isHealthy = healthy;
+      return this;
+    }
+
+    public Builder setStatus(String s) {
+      this.status = s;
+      return this;
+    }
+
+  }
+}

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/api/deviceplugin/DevicePlugin.java

@@ -0,0 +1,65 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hadoop.yarn.server.nodemanager.api.deviceplugin;
+
+import java.util.Set;
+
+/**
+ * A must interface for vendor plugin to implement.
+ * */
+public interface DevicePlugin {
+  /**
+   * Called first when device plugin framework wants to register.
+   * @return DeviceRegisterRequest {@link DeviceRegisterRequest}
+   * */
+  DeviceRegisterRequest getRegisterRequestInfo()
+      throws Exception;
+
+  /**
+   * Called when update node resource.
+   * @return a set of {@link Device}, {@link java.util.TreeSet} recommended
+   * */
+  Set<Device> getDevices() throws Exception;
+
+  /**
+   * Asking how these devices should be prepared/used
+   * before/when container launch. A plugin can do some tasks in its own or
+   * define it in DeviceRuntimeSpec to let the framework do it.
+   * For instance, define {@code VolumeSpec} to let the
+   * framework to create volume before running container.
+   *
+   * @param allocatedDevices A set of allocated {@link Device}.
+   * @param yarnRuntime Indicate which runtime YARN will use
+   *        Could be {@code RUNTIME_DEFAULT} or {@code RUNTIME_DOCKER}
+   *        in {@link DeviceRuntimeSpec} constants. The default means YARN's
+   *        non-docker container runtime is used. The docker means YARN's
+   *        docker container runtime is used.
+   * @return a {@link DeviceRuntimeSpec} description about environment,
+   * {@link         VolumeSpec}, {@link MountVolumeSpec}. etc
+   * */
+  DeviceRuntimeSpec onDevicesAllocated(Set<Device> allocatedDevices,
+      YarnRuntimeType yarnRuntime) throws Exception;
+
+  /**
+   * Called after device released.
+   * @param releasedDevices A set of released devices
+   * */
+  void onDevicesReleased(Set<Device> releasedDevices)
+      throws Exception;
+}

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/api/deviceplugin/DeviceRegisterRequest.java

@@ -0,0 +1,73 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hadoop.yarn.server.nodemanager.api.deviceplugin;
+
+import java.util.Objects;
+
+/**
+ * Contains plugin register request info.
+ * */
+public final class DeviceRegisterRequest {
+
+  // plugin's own version
+  private final String pluginVersion;
+  private final String resourceName;
+
+  private DeviceRegisterRequest(Builder builder) {
+    this.resourceName = Objects.requireNonNull(builder.resourceName);
+    this.pluginVersion = builder.pluginVersion;
+  }
+
+  public String getResourceName() {
+    return resourceName;
+  }
+
+  public String getPluginVersion() {
+    return pluginVersion;
+  }
+
+  /**
+   * Builder class for construct {@link DeviceRegisterRequest}.
+   * */
+  public final static class Builder {
+    private String pluginVersion;
+    private String resourceName;
+
+    private Builder() {}
+
+    public static Builder newInstance() {
+      return new Builder();
+    }
+
+    public DeviceRegisterRequest build() {
+      return new DeviceRegisterRequest(this);
+    }
+
+    public Builder setResourceName(String resName) {
+      this.resourceName = resName;
+      return this;
+    }
+
+    public Builder setPluginVersion(String plVersion) {
+      this.pluginVersion = plVersion;
+      return this;
+    }
+
+  }
+}