001 /**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019 package org.apache.hadoop.yarn.api.records;
020
021 import org.apache.hadoop.classification.InterfaceAudience.Private;
022 import org.apache.hadoop.classification.InterfaceAudience.Public;
023 import org.apache.hadoop.classification.InterfaceStability.Stable;
024 import org.apache.hadoop.classification.InterfaceStability.Unstable;
025 import org.apache.hadoop.yarn.api.ApplicationMasterProtocol;
026 import org.apache.hadoop.yarn.api.ContainerManagementProtocol;
027 import org.apache.hadoop.yarn.util.Records;
028
029 /**
030 * <p><code>Container</code> represents an allocated resource in the cluster.
031 * </p>
032 *
033 * <p>The <code>ResourceManager</code> is the sole authority to allocate any
034 * <code>Container</code> to applications. The allocated <code>Container</code>
035 * is always on a single node and has a unique {@link ContainerId}. It has
036 * a specific amount of {@link Resource} allocated.</p>
037 *
038 * <p>It includes details such as:
039 * <ul>
040 * <li>{@link ContainerId} for the container, which is globally unique.</li>
041 * <li>
042 * {@link NodeId} of the node on which it is allocated.
043 * </li>
044 * <li>HTTP uri of the node.</li>
045 * <li>{@link Resource} allocated to the container.</li>
046 * <li>{@link Priority} at which the container was allocated.</li>
047 * <li>
048 * Container {@link Token} of the container, used to securely verify
049 * authenticity of the allocation.
050 * </li>
051 * </ul>
052 * </p>
053 *
054 * <p>Typically, an <code>ApplicationMaster</code> receives the
055 * <code>Container</code> from the <code>ResourceManager</code> during
056 * resource-negotiation and then talks to the <code>NodeManager</code> to
057 * start/stop containers.</p>
058 *
059 * @see ApplicationMasterProtocol#allocate(org.apache.hadoop.yarn.api.protocolrecords.AllocateRequest)
060 * @see ContainerManagementProtocol#startContainers(org.apache.hadoop.yarn.api.protocolrecords.StartContainersRequest)
061 * @see ContainerManagementProtocol#stopContainers(org.apache.hadoop.yarn.api.protocolrecords.StopContainersRequest)
062 */
063 @Public
064 @Stable
065 public abstract class Container implements Comparable<Container> {
066
067 @Private
068 @Unstable
069 public static Container newInstance(ContainerId containerId, NodeId nodeId,
070 String nodeHttpAddress, Resource resource, Priority priority,
071 Token containerToken) {
072 Container container = Records.newRecord(Container.class);
073 container.setId(containerId);
074 container.setNodeId(nodeId);
075 container.setNodeHttpAddress(nodeHttpAddress);
076 container.setResource(resource);
077 container.setPriority(priority);
078 container.setContainerToken(containerToken);
079 return container;
080 }
081
082 /**
083 * Get the globally unique identifier for the container.
084 * @return globally unique identifier for the container
085 */
086 @Public
087 @Stable
088 public abstract ContainerId getId();
089
090 @Private
091 @Unstable
092 public abstract void setId(ContainerId id);
093
094 /**
095 * Get the identifier of the node on which the container is allocated.
096 * @return identifier of the node on which the container is allocated
097 */
098 @Public
099 @Stable
100 public abstract NodeId getNodeId();
101
102 @Private
103 @Unstable
104 public abstract void setNodeId(NodeId nodeId);
105
106 /**
107 * Get the http uri of the node on which the container is allocated.
108 * @return http uri of the node on which the container is allocated
109 */
110 @Public
111 @Stable
112 public abstract String getNodeHttpAddress();
113
114 @Private
115 @Unstable
116 public abstract void setNodeHttpAddress(String nodeHttpAddress);
117
118 /**
119 * Get the <code>Resource</code> allocated to the container.
120 * @return <code>Resource</code> allocated to the container
121 */
122 @Public
123 @Stable
124 public abstract Resource getResource();
125
126 @Private
127 @Unstable
128 public abstract void setResource(Resource resource);
129
130 /**
131 * Get the <code>Priority</code> at which the <code>Container</code> was
132 * allocated.
133 * @return <code>Priority</code> at which the <code>Container</code> was
134 * allocated
135 */
136 @Public
137 @Stable
138 public abstract Priority getPriority();
139
140 @Private
141 @Unstable
142 public abstract void setPriority(Priority priority);
143
144 /**
145 * Get the <code>ContainerToken</code> for the container.
146 * <p><code>ContainerToken</code> is the security token used by the framework
147 * to verify authenticity of any <code>Container</code>.</p>
148 *
149 * <p>The <code>ResourceManager</code>, on container allocation provides a
150 * secure token which is verified by the <code>NodeManager</code> on
151 * container launch.</p>
152 *
153 * <p>Applications do not need to care about <code>ContainerToken</code>, they
154 * are transparently handled by the framework - the allocated
155 * <code>Container</code> includes the <code>ContainerToken</code>.</p>
156 *
157 * @see ApplicationMasterProtocol#allocate(org.apache.hadoop.yarn.api.protocolrecords.AllocateRequest)
158 * @see ContainerManagementProtocol#startContainers(org.apache.hadoop.yarn.api.protocolrecords.StartContainersRequest)
159 *
160 * @return <code>ContainerToken</code> for the container
161 */
162 @Public
163 @Stable
164 public abstract Token getContainerToken();
165
166 @Private
167 @Unstable
168 public abstract void setContainerToken(Token containerToken);
169 }